{a.snapshot?.originalReadError && !a.readError ? {a.zh ? "已保存原文暂不可读,当前语言的分析状态仍保留。" : "The saved original could not be read. The current language’s analysis state is preserved."} :
- {a.pack ? (a.zh ? "刷新失败,保留上次结果。" : "Refresh failed. Showing the last result.")
+ {onBrowseStudies ? (a.zh ? "无法读取链接指定的解读。" : "The linked study version could not be read.")
+ : a.pack ? (a.zh ? "刷新失败,保留上次结果。" : "Refresh failed. Showing the last result.")
: (a.zh ? "暂时无法读取分析。" : "Analysis could not be read.")}}
+ {onBrowseStudies ? : null}
{locale === "zh-CN"
+ ? "连接信息读取自本机管家私有文件,不在此表单收集;记忆按已验证发言人隔离保存,超时不阻塞正常回复,也不会进入群聊或转交给工作 Agent。"
+ : "Connection settings stay in the private local steward file outside this form. Memory stays isolated per verified speaker, fails open on timeout, and never enters group chats or worker handoffs."}
+
+ ) : null}
+
{selected.capability_id === "pull_request_review" ? (
diff --git a/apps/presentation/dashboard/src/features/personal-workspace/personal-workspace-contract.test.mjs b/apps/presentation/dashboard/src/features/personal-workspace/personal-workspace-contract.test.mjs
index 0fdc7b1162..cf2ed749d0 100644
--- a/apps/presentation/dashboard/src/features/personal-workspace/personal-workspace-contract.test.mjs
+++ b/apps/presentation/dashboard/src/features/personal-workspace/personal-workspace-contract.test.mjs
@@ -502,11 +502,12 @@ for (const capabilityId of [
"pull_request_review",
"reward_memory",
"steward_executor",
+ "steward_memory",
]) {
const matches = capabilityLocalization.match(new RegExp(`${capabilityId}:`, "g")) ?? [];
assert.equal(matches.length, 2, `${capabilityId} has English and Simplified Chinese metadata`);
}
-for (const fieldKey of ["agent_orders", "allowed_domains", "coordinator_agent_id", "eligible_endpoints", "enabled", "executor_endpoint", "executor_model", "executor_reasoning_effort", "max_children", "profile", "profile_preset", "review_order", "route_ref", "safe_fix", "selection_policy", "strict_receipt", "timezone"]) {
+for (const fieldKey of ["agent_orders", "allowed_domains", "auto_recall", "coordinator_agent_id", "eligible_endpoints", "enabled", "executor_endpoint", "executor_model", "executor_reasoning_effort", "max_children", "profile", "profile_preset", "recall_timeout_seconds", "review_order", "route_ref", "safe_fix", "selection_policy", "strict_receipt", "timezone", "user_space"]) {
const matches = capabilityLocalization.match(new RegExp(`^\\s+${fieldKey}:`, "gm")) ?? [];
assert.equal(matches.length, 2, `${fieldKey} has English and Simplified Chinese field copy`);
}
diff --git a/apps/presentation/dashboard/src/features/personal-workspace/personal-workspace-page.tsx b/apps/presentation/dashboard/src/features/personal-workspace/personal-workspace-page.tsx
index 94e96ece80..66f5c99f70 100644
--- a/apps/presentation/dashboard/src/features/personal-workspace/personal-workspace-page.tsx
+++ b/apps/presentation/dashboard/src/features/personal-workspace/personal-workspace-page.tsx
@@ -1832,10 +1832,21 @@ export function PersonalWorkspacePage({
// not have a Turn to revisit.
.filter(proposal => proposal.actionKind !== "todo.create" || proposal.status !== "applied"
|| Boolean(proposal.reviewPlan?.taskExecution));
- const restored = Object.fromEntries(restoreable.map((proposal) => [proposal.previewId, proposal]));
const previousIds = restoredProposalIdsRef.current;
- restoredProposalIdsRef.current = new Set(Object.keys(restored));
- setProposals((current) => ({...Object.fromEntries(Object.entries(current).filter(([id]) => !previousIds.has(id))), ...restored}));
+ restoredProposalIdsRef.current = new Set(restoreable.map(proposal => proposal.previewId));
+ setProposals((current) => {
+ const next = Object.fromEntries(Object.entries(current).filter(([id]) => !previousIds.has(id)));
+ for (const proposal of restoreable) {
+ const previous = current[proposal.previewId];
+ // The stored confirmation outlives a failed dispatch attempt.
+ // Keep the local reason until readback observes a different confirmation.
+ const retryError = proposal.reviewPlan?.retryOriginal && previous?.reviewPlan?.retryOriginal
+ && previous.actionKind === proposal.actionKind && previous.goalId === proposal.goalId
+ && previous.updatedAt === proposal.updatedAt ? previous.errorMessage : undefined;
+ next[proposal.previewId] = retryError ? { ...proposal, errorMessage: retryError } : proposal;
+ }
+ return next;
+ });
// The manager conversation shows the cards this channel offered: a team
// plan the steward proposed from here is confirmed here, instead of the
// owner hunting for the Goal whose workspace happens to hold the card.
@@ -2140,7 +2151,7 @@ export function PersonalWorkspacePage({
: null;
const lifecycleChange = options.lifecycleProjection ?? inferredLifecycleChange;
setActionFeedback(t("feedback.applying", { title: proposal.title }));
- const applying = { ...proposal, reviewPlan: proposal.reviewPlan ? { ...proposal.reviewPlan, interaction: "pending" as const, reason: "apply_pending" as const, canApply: false as const } : undefined, status: "applying" as const };
+ const applying = { ...proposal, errorMessage: undefined, reviewPlan: proposal.reviewPlan ? { ...proposal.reviewPlan, interaction: "pending" as const, reason: "apply_pending" as const, canApply: false as const } : undefined, status: "applying" as const };
setProposals((current) => ({ ...current, [proposal.previewId]: applying }));
if (showDrawer) setSelection({ item: applying, kind: "proposal" });
let applyingSelection = selectionRevision.current;
diff --git a/apps/presentation/dashboard/src/features/personal-workspace/research-case-study.tsx b/apps/presentation/dashboard/src/features/personal-workspace/research-case-study.tsx
index 4487639894..35ab8f6e18 100644
--- a/apps/presentation/dashboard/src/features/personal-workspace/research-case-study.tsx
+++ b/apps/presentation/dashboard/src/features/personal-workspace/research-case-study.tsx
@@ -62,11 +62,15 @@ export function ResearchCaseStudy({study, zh, historical, active, scope, navigat
onCitationLocationChange: (hash: string) => void;
}) {
const article = useRef(null);
+ const currentStudy = useRef(study);
+ currentStudy.current = study;
const openCitation = useRef(onCitation);
openCitation.current = onCitation;
- const [missingCitation, setMissingCitation] = useState(false);
+ const [missingAnchor, setMissingAnchor] = useState("");
const {url, goalId, packId, namespace, follow} = navigation;
const prefix = `${caseChapterHashPrefix.slice(1)}${namespace ? namespace + '-' : ''}${packId}-`;
+ // A reread can replace the study object while the saved version and address
+ // stay the same. Only navigation should run chapter and citation restoration.
useEffect(() => {
if (!active) return;
let frame = 0;
@@ -85,23 +89,27 @@ export function ResearchCaseStudy({study, zh, historical, active, scope, navigat
// into a source identifier or range for the evidence API.
const match = scoped ? /^([a-zA-Z0-9_-]*)~([1-9][0-9]?)$/.exec(hash.slice(prefix.length + 1)) : null;
const section = match?.[1];
- const citations = section ? study.sections.find(item => item.id === section)?.citations : study.citations;
+ const savedStudy = currentStudy.current;
+ const citations = section ? savedStudy.sections.find(item => item.id === section)?.citations : savedStudy.citations;
const citation = match ? citations?.[Number(match[2]) - 1] : undefined;
const origin = document.getElementById(hash.slice(1));
if (!citation || !origin || !article.current?.contains(origin)) {
- setMissingCitation(true);
+ setMissingAnchor(hash);
return;
}
- setMissingCitation(false);
+ setMissingAnchor("");
const disclosure = origin.closest('details');
if (disclosure) disclosure.open = true;
openCitation.current(citation, origin, {hash, chapterHash: section ? `#${prefix}${section}` : ""});
return;
}
- setMissingCitation(false);
- if (!scoped) return;
- const chapter = document.getElementById(hash.slice(1));
- if (chapter && article.current?.contains(chapter) && chapter.getClientRects().length) focusChapter(chapter);
+ const chapter = scoped ? document.getElementById(hash.slice(1)) : null;
+ if (chapter && article.current?.contains(chapter) && chapter.getClientRects().length) {
+ setMissingAnchor("");
+ focusChapter(chapter);
+ } else {
+ setMissingAnchor(hash.startsWith(caseChapterHashPrefix) ? hash : "");
+ }
});
};
restore();
@@ -112,7 +120,7 @@ export function ResearchCaseStudy({study, zh, historical, active, scope, navigat
window.removeEventListener('popstate', restore);
window.removeEventListener('hashchange', restore);
};
- }, [active, goalId, packId, prefix, study, onCitationLocationChange]);
+ }, [active, goalId, packId, prefix, onCitationLocationChange]);
const citationLinks = (citations: AssessmentCitation[], section = "") =>
@@ -152,7 +162,7 @@ export function ResearchCaseStudy({study, zh, historical, active, scope, navigat
if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.altKey || e.shiftKey) return;
e.preventDefault();
onCitationLocationChange(href.hash);
- setMissingCitation(false);
+ setMissingAnchor("");
follow(href);
const chapter = document.getElementById(id);
if (chapter && article.current?.contains(chapter)) focusChapter(chapter);
diff --git a/apps/presentation/dashboard/src/features/personal-workspace/research-record-export.ts b/apps/presentation/dashboard/src/features/personal-workspace/research-record-export.ts
index fff0532b21..40bac0ce58 100644
--- a/apps/presentation/dashboard/src/features/personal-workspace/research-record-export.ts
+++ b/apps/presentation/dashboard/src/features/personal-workspace/research-record-export.ts
@@ -1,7 +1,7 @@
import type {ExploreHistoryEvent} from "../../../../../../loopx/control_plane/presentation/explore_history.ts";
import {searchResearchRecords, type ResearchRecordDisplay} from "./research-record-search.ts";
-/** A portable reading snapshot, not an import format or an acceptance receipt.
+/** A portable reading snapshot.
* Export canonical records, never translated/analysed display replacements.
* Source endpoints are deliberately absent: opening a file needs no connection.
*/
diff --git a/apps/presentation/dashboard/src/features/personal-workspace/research-record-search.ts b/apps/presentation/dashboard/src/features/personal-workspace/research-record-search.ts
index ce3a92682c..80c9ebb718 100644
--- a/apps/presentation/dashboard/src/features/personal-workspace/research-record-search.ts
+++ b/apps/presentation/dashboard/src/features/personal-workspace/research-record-search.ts
@@ -2,7 +2,7 @@ import type {ExploreHistoryEvent, ExploreHistoryNode} from "../../../../../../lo
import type {ExploreFindingSections} from "../../../../../../loopx/control_plane/presentation/explore_timeline.ts";
/** The history reader supplies its already qualified, current-language projection.
- * This search neither validates a translation nor borrows another snapshot. */
+ * */
export type ResearchRecordDisplay = {
events?: ReadonlyMap;
sections?: ReadonlyMap;
diff --git a/apps/presentation/dashboard/src/features/personal-workspace/research-record-versions.ts b/apps/presentation/dashboard/src/features/personal-workspace/research-record-versions.ts
index c6aebc18aa..02369d3bd0 100644
--- a/apps/presentation/dashboard/src/features/personal-workspace/research-record-versions.ts
+++ b/apps/presentation/dashboard/src/features/personal-workspace/research-record-versions.ts
@@ -8,7 +8,7 @@ export function researchRecordVersions(events: readonly ExploreHistoryEvent[], s
&& event.event_kind === selected.event_kind && event.result_id === selected.result_id);
}
-// Local display fields, not a new evidence or lifecycle vocabulary.
+// Local display fields.
export const researchComparisonFields = ["title", "summary", "status", "blocked_reason", "evidence_refs",
"measurements", "confidence", "run_id", "agent_id", "node_kind", "node_id", "parent_id",
"from_node", "to_node", "edge_type", "supersedes", "execution_observation"] as const;
diff --git a/apps/presentation/dashboard/src/features/personal-workspace/research-usage-selection.ts b/apps/presentation/dashboard/src/features/personal-workspace/research-usage-selection.ts
index f500e4223f..08130e66a3 100644
--- a/apps/presentation/dashboard/src/features/personal-workspace/research-usage-selection.ts
+++ b/apps/presentation/dashboard/src/features/personal-workspace/research-usage-selection.ts
@@ -1,6 +1,6 @@
import type {TrajectorySolverUsage} from "../../../../../../loopx/control_plane/capabilities/trajectory_assessment_types.js";
-/** Presentation arithmetic over one already-qualified capture, not a ledger. */
+/** Presentation arithmetic over one already-qualified capture. */
export function researchUsageRows(usage: TrajectorySolverUsage) {
const complete = usage.turns.map(turn => ({...turn, incomplete: false}));
const partial = [...(usage.interrupted_turns ?? [])];
diff --git a/apps/presentation/dashboard/src/features/personal-workspace/todo-completion-feedback.ts b/apps/presentation/dashboard/src/features/personal-workspace/todo-completion-feedback.ts
index 5e7315bcda..1db714206a 100644
--- a/apps/presentation/dashboard/src/features/personal-workspace/todo-completion-feedback.ts
+++ b/apps/presentation/dashboard/src/features/personal-workspace/todo-completion-feedback.ts
@@ -21,7 +21,7 @@ export function parseTodoCompletionProof(text: string): {
} catch { return null; }
}
-/** Present the terminal owner's refusal; neither inspect nor acquire a lease. */
+/** Present the terminal owner's refusal; */
export function todoCompletionProofRequired(error: unknown): boolean {
return error instanceof ChatApiError && (error.payload.error_code === "handoff_mode_requires_lease"
|| error.payload.error_code === "lease_fence_required");
diff --git a/apps/presentation/site/src/time-machine/records.ts b/apps/presentation/site/src/time-machine/records.ts
index cbfb8a6f19..fa2282dfa0 100644
--- a/apps/presentation/site/src/time-machine/records.ts
+++ b/apps/presentation/site/src/time-machine/records.ts
@@ -1,4 +1,4 @@
-/** Verbatim public capture reader, not an Explore state reducer or validator.
+/** Verbatim public capture reader.
* Explore owns v0 semantics. Pinned bytes prevent a different capture or edited
* record from silently acquiring these editorial scenes. Status stays source text.
*/
diff --git a/docs/architecture/rfcs/controller-executor-unified-contract-v0/contract-and-context.md b/docs/architecture/rfcs/controller-executor-unified-contract-v0/contract-and-context.md
index 71e2fc78b1..335ae7f4f4 100644
--- a/docs/architecture/rfcs/controller-executor-unified-contract-v0/contract-and-context.md
+++ b/docs/architecture/rfcs/controller-executor-unified-contract-v0/contract-and-context.md
@@ -579,6 +579,12 @@ design, not a claim that these paths have changed.
| `turn_driver/decision_capture.py` and `cli_commands/quota_capture.py` | Reuse immutable capture, validated readers and full/delta delivery. Fresh delivery and saved-capture recovery must reconstruct the same contract; do not reuse a continuity baseline for a different projection merely because its Turn identity matches. |
| `benchmark/runtime/worker.py`, `benchmark/runtime/sessions.py` and `scripts/external_scheduler_worker.py` | Migrate the product entry they actually invoke. Keep evaluation setup and outer wake ownership; do not add benchmark-only conversion or count a managed-host test as attached-host acceptance. |
+The current heartbeat generator uses `interaction_contract` for target
+selection, required reads and exact Turn settlement. Saved bootstrap wrappers
+reload that generator on wake. All in-tree generation callers use this route,
+so the old envelope-specific instructions and their prompt budget allowance
+are retired. Previously captured work still uses its recorded recovery reader.
+
Before replacing any seam, its implementation PR records source path, field or
instruction clause, current readers, target owner, representation, recovery and
retirement condition. Relocation must include reference resolution; an omitted
diff --git a/docs/architecture/rfcs/controller-executor-unified-contract-v0/contract-and-context.zh-CN.md b/docs/architecture/rfcs/controller-executor-unified-contract-v0/contract-and-context.zh-CN.md
index e0775360bf..efc1e6ee5d 100644
--- a/docs/architecture/rfcs/controller-executor-unified-contract-v0/contract-and-context.zh-CN.md
+++ b/docs/architecture/rfcs/controller-executor-unified-contract-v0/contract-and-context.zh-CN.md
@@ -431,6 +431,11 @@ Draft,不是仅等待评审。尚无模型或成本收益证据。历史 effec
| `turn_driver/decision_capture.py` 与 `cli_commands/quota_capture.py` | 复用不可变 capture、校验读取器和 full/delta 交付。首次交付和保存后恢复必须重建同一契约;不能仅因 Turn 身份相同,就把某投影的 continuity baseline 用于另一投影。 |
| `benchmark/runtime/worker.py`、`benchmark/runtime/sessions.py` 与 `scripts/external_scheduler_worker.py` | 迁移它们实际调用的产品入口。保留评估配置与外层唤醒归属,不新增 benchmark 专用转换,也不把 managed-host 测试算作 attached-host 验收。 |
+当前 heartbeat 生成器通过 `interaction_contract` 交付目标选择、必读和原 Turn
+结算。已保存的 bootstrap 在唤醒时重新调用该生成器。树内所有生成调用都已采用
+此路径,因此退役旧 envelope 专用指令和额外提示词预算。已有 capture 中的工作
+继续由记录的恢复 reader 读取。
+
替换任一接缝前,实现 PR 记录源路径、字段或指令条款、当前 reader、目标 owner、表示、
恢复与退役条件。字段搬迁须包含引用解析;删除诊断须证明其中不含动作、权限、必读或
验收义务。未知数据不得静默消失;未知的必需执行语义也不能靠转发 JSON 就变安全,
diff --git a/docs/architecture/rfcs/long-horizon-harness-benchmark-research-program-v0.md b/docs/architecture/rfcs/long-horizon-harness-benchmark-research-program-v0.md
index e8c4986f07..2703ae9548 100644
--- a/docs/architecture/rfcs/long-horizon-harness-benchmark-research-program-v0.md
+++ b/docs/architecture/rfcs/long-horizon-harness-benchmark-research-program-v0.md
@@ -937,8 +937,14 @@ The [Research human-attention observer](../../reference/trajectory-assessment.md
now reads source-bound human inputs, separate active/wait interval unions and
recorded avoidable-input candidates through the existing pack and citation owner.
Recorder classifications, partial timing and historical sources remain explicit.
-Synthetic packaged-reader checks qualify this reading path; live capture coverage,
-calibrated necessity and lower attention for equal accepted quality remain unqualified.
+Synthetic packaged-reader checks qualify this reading path. The live producer
+boundary is now qualified only for authenticated LoopX Lark `operation.execute`
+and `team.plan` card decisions, explicitly bound to a Goal pack and UTC window.
+It preserves partial coverage, treats delivery-to-confirmation as waiting, leaves
+active attention and necessity unknown, rejects multi-principal windows to retain
+the single-human contract, and labels conservative pre-marker backfill as legacy.
+Unauthenticated, pending/expired and runtime-native approval capture, calibrated
+necessity and lower attention for equal accepted quality remain unqualified.
### 6.5 Benchmark integrity and anti-cheating
diff --git a/docs/architecture/rfcs/long-horizon-harness-benchmark-research-program-v0.zh-CN.md b/docs/architecture/rfcs/long-horizon-harness-benchmark-research-program-v0.zh-CN.md
index 1de6a4f4af..e979e01299 100644
--- a/docs/architecture/rfcs/long-horizon-harness-benchmark-research-program-v0.zh-CN.md
+++ b/docs/architecture/rfcs/long-horizon-harness-benchmark-research-program-v0.zh-CN.md
@@ -729,8 +729,12 @@ replan 前 checkpoint、恢复、接收者读回及下一次可观察动作的
[研究页人工注意力 observer](../../reference/trajectory-assessment.md#human-attention-in-research-optional)
现在通过既有 pack 与引用 owner 读取有来源的人工介入、分别取并集的主动/等待时间
及标记可避免的介入候选。记录方分类、部分时间覆盖和历史来源保持明确。
-合成打包阅读检查只验收此读取路径;真实采集覆盖、必要性校准及同等验收质量下的
-注意力降低仍未验收。
+合成打包阅读检查验收此读取路径。真实 producer 当前仅验收经过认证、由目标 Goal
+pack 与 UTC 时间窗显式绑定的 LoopX Lark `operation.execute` 与 `team.plan` 卡片决定。
+该边界保留部分覆盖,把投递到确认记为等待,主动投入和必要性保持未知;为保留单人
+记录契约,它拒绝包含多个 principal 的窗口,并将 marker 引入前的保守回填标为 legacy。
+未认证、pending/expired、runtime-native approval 的采集,必要性校准及同等验收质量下
+的注意力降低仍未验收。
### 6.5 Benchmark integrity 与反作弊
diff --git a/docs/architecture/rfcs/monorepo-distribution-split-v0.md b/docs/architecture/rfcs/monorepo-distribution-split-v0.md
index 6e5521ac0a..67ca1a7af9 100644
--- a/docs/architecture/rfcs/monorepo-distribution-split-v0.md
+++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.md
@@ -4,7 +4,7 @@
- **Delivery maturity:** Proposal
- **Authors / owners:** LoopX maintainers
- **Created:** 2026-09-26
-- **Last normative revision:** 2026-11-17
+- **Last normative revision:** 2026-11-19
- **Implementation baseline:** packaging inventory `2f3d13ae9`; runtime composition audit `9cae3b28939f72fa4aadab5cfe49e19bcbdab372`
- **Related contracts:** [TypeScript Control-Plane Migration v0](typescript-control-plane-migration-v0.md), [Extensions reference](../../reference/extensions.md), [Capability catalog](../../../loopx/capabilities/README.md), [Overall Roadmap v0](loopx-overall-roadmap-v0.md) (S2, S8, S12), [import-boundary tests](../../../tests/architecture/test_control_plane_import_boundaries.py)
- **Tracking issue:** [#5072](https://github.com/loopx-project/loopx/issues/5072)
@@ -35,7 +35,7 @@ retain their original baselines.
wheel is replaced over time by `loopx-core`, `loopx-workspace`, and
per-capability packages under `packages/`, with `loopx` retained as a
meta-package that depends on all of them.
-3. **Top-level regrouping happens before any packaging change.** `loopx/chat_*`
+3. **Regroup the selected dependency closure as needed for independent packaging.** `loopx/chat_*`
moves to `loopx/chat/`, `loopx/*_goal_mode/` moves to `loopx/hosts/`, with
compatibility re-exports for established public imports for at least one minor
release. Internal-only callers move together and the old internal entry is deleted.
@@ -63,6 +63,20 @@ can be installed, not what every command must load. Installing standard grants
no service activation or permission. Existing defaults and machine-enforced
work obligations remain until a qualified, explicitly disclosed migration.
+The immediate outcome is an independently installed core that executes a task,
+recovers its original result and returns evidence. Unrelated directory moves,
+workspace packaging or another model session do not block that core-artifact
+slice; full M3 retains its complete distribution acceptance. Ordinary callers
+supply a task and consequential constraints, without first learning Vision,
+Quota, Lease or method names. The host carries bookkeeping; relevant permission,
+budget, uncertainty and recovery decisions remain visible when needed.
+
+The **10% complexity / 90% current-function coverage** target remains an unproven
+hypothesis. Fix a versioned journey denominator and compare necessary concepts,
+mandatory steps, loaded/activated code, model reads, complete costs and accepted
+outcomes. Report kernel-only and assembled coverage; do not drop specialized
+journeys from the denominator or treat code counts as model benefit.
+
## 2. Problem and motivation
A developer who wants a CLI-only or kernel-only LoopX installs the same wheel as
@@ -269,6 +283,19 @@ contract into prose guidance. The kernel is a cohesive set of domains, not one
large file. The adjacent refactor should localize the next change and preserve
characterized behavior.
+### Required mechanisms and optional task methods
+
+Core owns legal scoped work, durable evidence, stop, budget and original-attempt
+recovery. Bench, workbench and manager compose specialized workflows around the
+same owners. Their absence must not block unrelated authorized core work.
+**Yardstick is an independently optional decision method, not a provider or a
+mandatory kernel stage.** Methods choose how to reason or measure; providers
+supply execution, storage or concrete external operations. Reuse existing
+capability owners and `yardstick_enabled`; add no method registry, provider id
+or enable switch. Ordinary result validation remains required when a method is
+off. Existing records, configured obligations, authority and defaults survive;
+method/dependency removal needs its own absence, parity and recovery evidence.
+
### Presets over the distribution tiers
| Composition | Required content | Explicit optional content |
@@ -283,6 +310,16 @@ flag applied after standard fully initializes. A host-free read-only kernel
library does not qualify that executable preset. Exact contents and the first
supported host/authority combination are D2/D5 decisions.
+The initial proposed **Standard** selection is `agent-turn-recall` for relevant
+prior guidance, `issue-fix` for validated repository changes, and
+`pull-request-review` for delivery review. These retain their existing capability
+owners and default-off settings; installation grants no source access, starts
+no watcher and authorizes no publication or merge. Load only the selected task's
+implementation. Basic recovery stays in Minimal without advisory recall.
+Yardstick, Stride, research/benchmark machinery and manager routing remain
+separate optional additions. This selects the R2 target; the current monolithic
+and core-candidate wheels do not yet implement that isolated package selection.
+
Keep composition, managed/attached mode, host provider, one/two model sessions,
storage provider and benchmark arm independent. Minimal does not imply attached,
standard does not require two model sessions, and research does not mean
@@ -419,6 +456,11 @@ contract explicitly requires their receipt. Batch best-effort telemetry only;
do not defer authoritative receipt persistence, weaken fsync/transaction
guarantees or cache stale permission/lease decisions to meet a timing target.
+For an admitted ordinary task, the built-in Worker view omits known empty
+Todo summary lanes. The selected task, nonempty lanes, counts, references and
+upstream truncation remain visible. The signed source and original reader
+retain the complete summaries for recovery and diagnosis.
+
### Governed lifecycle and external effects
Use existing Goal/Agent/work/Turn identities, revisions, leases, effect ids and
@@ -489,6 +531,13 @@ defaults or a new LoopX model loop. Pinned sources are in Appendix C.
## 7. Safety, privacy, and compatibility
+Ordinary C1 composition and replay use shared Explore guidance and exact
+context references. An empty read with graph and planning disabled returns
+the existing disabled view before loading the graph projector. A scoped
+Explore read loads Yardstick when its graph is available and the Goal enables
+evaluation. Settings, evidence identities, and recovery remain with the
+current Goal and Explore owners.
+
- **Default-off / feature-off parity:** absent `loopx-workspace` or capability
packages behave like the existing extension off state (I4). No command
silently falls back to another implementation.
@@ -611,6 +660,14 @@ moves; it does not qualify the kernel. R3/R4 are optional and do not block a
qualified CLI or managed task. No unused provider, field or framework is added
ahead of its real caller. Report the applied/deferred adjacent refactor in each PR.
+### Core discovery checkpoint — 2026-11-19
+
+| Boundary | Delivered delta / evidence | Still open |
+| --- | --- | --- |
+| V1/V3, capability discovery | Benchmark package exports resolve their selected existing owner on demand, retaining all 199 public symbols and their order; explicit star imports still request all. Help/list/detail succeed with benchmark execution implementations unavailable, no Node, process launch, network or state writes. | Does not remove benchmark files from the wheel or qualify absent-capability installation. |
+| Metadata and active consumers | The same catalog and all 25 details are byte-identical to the frozen `main@e235cde9c` workload; 53 CLI help/list/detail/unknown-id observations match. Discovery loads 2 benchmark children instead of 28, and 298 LoopX modules instead of 326. Existing benchmark semantics and canonical export identities remain unchanged. | Import counts are not latency, total cost, model benefit or full D2/D5 closure. |
+| Acceptance and continuation | 52 installed-core discovery/execution/context/recovery cases pass on the rebuilt artifact; 383 selected consumer cases and 43 architecture/documentation cases pass separately. No new state owner, provider id, activation toggle or top-level module. | Keep R1/M3 and V1–V5/V10 open; continue capability package isolation and selected Standard delivery. Public-channel C1 qualification remains with its release owner. |
+
### Subtraction Gate & Anti-Context-Gravity Rules
diff --git a/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md b/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md
index 2303929af4..673316d11c 100644
--- a/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md
+++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md
@@ -4,7 +4,7 @@
- **交付成熟度:** Proposal
- **作者 / 负责人:** LoopX maintainers
- **创建:** 2026-09-26
-- **最近规范性修订:** 2026-11-17
+- **最近规范性修订:** 2026-11-19
- **实现基线:** 发行盘点 `2f3d13ae9`;运行时装配审计 `9cae3b28939f72fa4aadab5cfe49e19bcbdab372`
- **相关契约:** [TypeScript 控制面迁移 v0](typescript-control-plane-migration-v0.zh-CN.md)、[Extensions 参考](../../reference/extensions.md)、[Capability 目录](../../../loopx/capabilities/README.md)、[总体路线图 v0](loopx-overall-roadmap-v0.zh-CN.md)(S2、S8、S12)、[import 边界测试](../../../tests/architecture/test_control_plane_import_boundaries.py)
- **跟踪 issue:** [#5072](https://github.com/loopx-project/loopx/issues/5072)
@@ -25,7 +25,7 @@
1. **仓库保持单一 monorepo。** 一条 PR 流程、一套 CI、一个发布列车。拆成多个 Git 仓库是本 RFC 的非目标。
2. **安装物拆成多个发行物。** 单一 `loopx` wheel 逐步替换为 `loopx-core`、`loopx-workspace` 以及 `packages/` 下的按 capability 打包;`loopx` 保留为依赖全部子包的 meta-package。
-3. **先做顶层目录重组,再做打包变更。** `loopx/chat_*` 迁入 `loopx/chat/`,`loopx/*_goal_mode/` 迁入 `loopx/hosts/`,已建立的公开 import 保留至少一个 minor 版本的兼容 re-export;内部调用方一起迁移并删除旧内部入口。
+3. **按独立打包所需重组所选依赖闭包。** `loopx/chat_*` 迁入 `loopx/chat/`,`loopx/*_goal_mode/` 迁入 `loopx/hosts/`,已建立的公开 import 保留至少一个 minor 版本的兼容 re-export;内部调用方一起迁移并删除旧内部入口。
4. **新增一条架构测试钉住顶层增长。** `loopx/*.py` 的文件数只能减少,与现有零例外 import 边界测试并列。
5. **仅内核安装不得在 import 阶段要求 Node.js。** TS effect runtime 对有副作用的命令仍是必需的;缺失时必须以现有的类型化 `node_unavailable` 诊断呈现,而不是安装或 import 失败。
6. **不变:** 内核权威、CLI 兼容基线、extension 生命周期规则、公开/私有边界、全部稳定协议。
@@ -39,6 +39,15 @@ Minimal 必须执行并恢复真实的受治理任务;standard 围绕同一内
发行表定义可安装内容,不代表每条命令都必须加载。安装 standard 不授予服务激活或权限。
现有默认值与机器强制工作义务持续生效,直到合格且明确披露的迁移改变它们。
+当前优先结果是可独立安装、执行任务、恢复原结果并返回证据的 core。无关目录移动、
+workspace 打包或额外模型会话不阻塞这一 core 发行物切片;完整 M3 仍保留全部发行
+验收。普通调用者提供任务与关键约束,不必先学 Vision、Quota、Lease 或方法名称。
+Host 承担记账;必要的权限、预算、不确定性与恢复决策仍在相关时可见。
+
+**10% 复杂度/90% 当前功能覆盖率**仍是未验证假设。固定版本化用户旅程分母,比较
+必要概念、必经步骤、加载/启用代码、模型读取、完整成本和已验收成果。分别报告
+仅内核与组合后的覆盖率;不能从分母删除特化旅程,也不能以代码计数代替模型收益。
+
## 2. 问题与动机
只想要 CLI 或内核的开发者,安装的和运行桌面工作台、Lark 管家、全部内置 capability 的人是同一个 wheel。`2f3d13ae9` 上的历史发行盘点:
@@ -181,6 +190,16 @@ Planner 可以建议工作或 stride,所属迁移规则决定准入与义务
预设不能把机器强制的 `must_attempt_work` 契约变成文字 guidance。
内核是内聚领域的集合,不是一个大文件。相邻重构应让下一次修改更局部,并保持已刻画的行为。
+### 必要机制与可选任务方法
+
+Core 负责合法限定工作、持久证据、停止、预算及原 attempt 恢复。Bench、workbench、
+管家围绕相同 owner 组合特化工作流;它们缺席不能阻塞无关的已授权 core 工作。
+**Yardstick 是独立可选的决策方法,不是 provider 或强制内核阶段。** 方法选择如何
+推理或衡量;provider 提供执行、存储或具体外部操作。复用既有 capability owner 和
+`yardstick_enabled`,不增加方法 registry、provider id 或开关。关闭方法不免除普通
+结果验收。保留既有记录、已配置义务、权限与默认值;移除方法/依赖须独立证明组件
+缺席、一致性与恢复。
+
### 发行层之上的预设
| 装配 | 必需内容 | 显式可选内容 |
@@ -194,6 +213,13 @@ Minimal 是可执行装配,不是在 standard 完成全部初始化后加开
不带宿主的只读 kernel library 不构成可执行预设资格。
精确内容与首个受支持宿主/authority 组合由 D2/D5 决定。
+首批 **Standard** 选型提案为:`agent-turn-recall` 取回相关既有指导,`issue-fix`
+交付已验证仓库变更,`pull-request-review` 执行交付审查。保留各自既有 owner 和默认
+关闭设置;安装不授予来源访问、不启动 watcher,也不授权发布或合并。仅加载所选
+任务实现;可选指导召回缺席时,Minimal 仍保有基本恢复。Yardstick、Stride、研究/
+benchmark 机制与管家路由继续独立可选。这选定 R2 的目标,现有单体和 core 候选 wheel
+尚未实现该隔离分包组合。
+
装配、managed/attached 模式、宿主 provider、一个/两个模型 Session、存储 provider、benchmark arm
保持独立。Minimal 不意味着 attached,standard 不要求双模型 Session,research 不等于不受治理。
只发布已测组合,保留现有模式默认值;改变装配不能静默改变 binding 的执行 owner。
@@ -289,6 +315,10 @@ Capability 指令仅在适用时提供;authority 不能从 prompt 文字推导
其延迟不能进入准入/结算事务。只批处理尽力而为的 telemetry;不能为满足时间目标而延迟
authority receipt 持久化、弱化 fsync/事务保证,或缓存过期权限/租约决策。
+普通任务获准执行后,内置 Worker 视图省去已知为空的 Todo 摘要列表。所选任务、
+非空列表、计数、引用与来源截断信息继续可见。签名来源和原有读取入口保留完整摘要,
+供恢复与诊断使用。
+
### 受治理生命周期与外部副作用
通过统一工作契约使用既有 Goal/Agent/work/Turn 身份、revision、lease、effect id 与 receipt。
@@ -345,6 +375,10 @@ minimal 包含持久 shell、图像读取与 compaction。SDK minimal 还提供
## 7. 安全、隐私与兼容
+普通 C1 组装和重放沿用 Explore 的共享指引及精确上下文引用。图和规划关闭时,
+空读取在加载图投影前返回既有的关闭状态。有范围的 Explore 读取在图可用且 Goal
+启用评估时加载 Yardstick。设置、证据身份和恢复继续由当前 Goal 与 Explore 负责。
+
- **默认关闭 / 功能关闭一致性:** 缺失 `loopx-workspace` 或 capability 包时,行为等同现有 extension off state(I4)。没有命令会静默回退到另一实现。
- **公开/私有边界:** 不变。`loopx check` 继续扫描每个包;移动文件不改变其扫描类别。
- **旧读者/写者:** import shim(I3)覆盖已建立的公开 Python import。console script 保持名字;`loopx` meta-package 让 `pip install loopx` 在一个 minor 版本内行为完全一致。
@@ -443,6 +477,14 @@ M0–M5 保留原发行里程碑;R0–R4 是同一计划中的运行时和旅
R0 可以先于目录移动交付,但不代表内核合格。R3/R4 可选,不阻塞已合格的 CLI 或 managed 任务。
真实调用者出现前不增加闲置 provider、字段或框架。每个 PR 记录应用/推迟的相邻重构。
+### Core 发现入口检查点 — 2026-11-19
+
+| 边界 | 交付增量/证据 | 仍未完成 |
+| --- | --- | --- |
+| V1/V3,能力发现 | Benchmark 包公开符号按需解析到所选既有 owner,保留全部 199 个符号及顺序;显式星号导入仍请求全部。执行实现不可用且无 Node 时,帮助/列表/详情仍可用,无进程启动、网络或状态写入。 | 未从 wheel 删除 benchmark 文件,也不验收 capability 分包缺席安装。 |
+| 元数据与活跃调用方 | 同冻结 `main@e235cde9c` workload 的目录和全部 25 项详情逐字节一致;53 项 CLI 帮助/列表/详情/未知 id 观察一致。发现入口的 benchmark 子模块从 28 降到 2,LoopX 模块从 326 降到 298。保留 benchmark 语义及公开符号的 canonical 对象身份。 | Import 数量不代表时延、完整成本、模型收益或完整 D2/D5 闭包。 |
+| 验收与继续方向 | 重建发行物通过 52 项安装 core 发现/执行/上下文/恢复用例;383 项所选消费方与 43 项架构/文档用例分别通过。没有新增状态 owner、provider id、启用开关或顶层模块。 | R1/M3 与 V1–V5/V10 继续开放;下一步仍是 capability 分包隔离与所选 Standard 交付。公开渠道 C1 资格仍归既有 release owner。 |
+
### 减法门禁与反上下文重力规则
diff --git a/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.md b/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.md
index 9b0295d724..c4cab9b373 100644
--- a/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.md
+++ b/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.md
@@ -889,6 +889,11 @@ capability. Disabling removes the extra ordinary-Turn cue and rejects new
captures before primary commit, while historical findings and successful exact
replays remain readable.
+An Explore context read loads the Yardstick projector when the graph is
+available and the setting is enabled. Ordinary C1 reads use the shared
+guidance and exact references for the captured context. Prior decisions stay
+bound to their original source when selected or replayed.
+
The existing Research finding reader exposes the recorded target, outcome/proxy
metrics, source, next action and cost bound. The ordinary task-scoped Explore
context projects only that Todo's current target, a short next-choice cue and
diff --git a/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.zh-CN.md b/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.zh-CN.md
index 2d85b732ff..59952e0a0c 100644
--- a/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.zh-CN.md
+++ b/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.zh-CN.md
@@ -655,6 +655,9 @@ Explore evidence 可用;开启该设置不启动工作或自动开启其他 ca
关闭后移除普通 Turn 的新增提示,并在主提交前拒绝新 capture;历史 finding
及成功的精确重放仍可读。
+Explore 读取在图可用且设置已开启时加载 Yardstick 投影。普通 C1 使用共享指引和
+精确引用读取捕获的上下文。选中或重放既有决策时仍绑定原始来源。
+
既有 Research finding reader 展示记录的目标、成果/代理指标、来源、下一步和成本边界。
普通 task-scoped Explore context 只投影该 Todo 当前目标、下一选择短提示和反证引用。
既有 question-scoped 扩读命令返回完整决策、精确 profile 的反馈和前次执行归属;
diff --git a/docs/book/chapters/00-reading-guide.md b/docs/book/chapters/00-reading-guide.md
index 37a69cff4f..8481409fb5 100644
--- a/docs/book/chapters/00-reading-guide.md
+++ b/docs/book/chapters/00-reading-guide.md
@@ -91,7 +91,7 @@ T1 的一次写回可留下回执 R1,但它不自动关闭 G1 或接受整个
[选择正确的放置位置](./08-extension-placement.md)。
项目接入与开发者贡献共享基础模型,但没有先后依赖。Extension 是开发者贡献中的一种交付和
-lifecycle 选择,不是所有贡献的默认终点。
+lifecycle 选择。
## 这本书的主线
@@ -120,7 +120,7 @@ lifecycle 选择,不是所有贡献的默认终点。
概念章解释因果和设计取舍;实践章给出前提、动作、读回和失败出口;贡献章沿协议与实现寻找
第一处需要改变的边界。它们不必都写成同一张四列表,但不能把关键推理留给读者猜。
-状态机专题和附录供回查,不是要求第一次接入前全部背完的考试范围。
+状态机专题和附录供回查。
[项目接入章](05-connect-existing-project.md#three-completions)区分安装、接入与工作交付,
其[第一份交付](05-connect-existing-project.md#first-delivery)把 T1/T2、CI、决定与最终返回接在一起。
@@ -149,7 +149,7 @@ lifecycle 选择,不是所有贡献的默认终点。
这四问是教学与修订标准,不新增 schema、运行时义务或审批门禁。资料不足时,应明确
“尚不能判断什么、缺少哪项证据、由谁确认”;不能为了填满四格而猜测。
-拒绝也不是最终目标:条件补齐后要重新判断,保留已经发生的工作,并走向下一次合法行动。
+条件补齐后要重新判断,保留已经发生的工作,并走向下一次合法行动。
## 怎样理解书中的证据
@@ -221,7 +221,7 @@ node --version
为进展单位,不继续堆 leaf helper 与 bridge。
核对这一历史里程碑时,以 `v0.5.4` tag 和 release notes 为准。历史记录中的
-Stage 3/Stage 4 是阶段边界,不是当前支持矩阵;后续 cutover 与 CLI/App 收敛以
+Stage 3/Stage 4 是阶段边界;后续 cutover 与 CLI/App 收敛以
[TypeScript Control-Plane Migration RFC](/loopx/docs/architecture/rfcs/typescript-control-plane-migration-v0/)
的当前状态为准。`v0.5.4` 只交付了 Stage 3 的第一个 receipt-bound scheduler follow-up 切片;更广的
CLI/App convergence 与 Stage 4 distribution cleanup 仍是后续方向。
@@ -238,13 +238,12 @@ CLI/App convergence 与 Stage 4 distribution cleanup 仍是后续方向。
| Capability / Provider | Capability 由 package-owned catalog entry、真实 command 和 durable validation 共同定义;Provider/Extension 不继承 Kernel authority | [Capability Catalog](/loopx/docs/capabilities/) |
| Shared authority | file、NoKV 与 PostgreSQL provider 仍是 staged candidate;安装 Provider 不会改变默认本地 authority | [Shared Authority RFC](/loopx/docs/architecture/rfcs/shared-goal-authority-state-provider-v0/) |
-这张表是阅读导航,不是 release notes 的副本。某个 surface 是否可用,仍应从当前安装版本的
+这张表是阅读导航。某个 surface 是否可用,仍应从当前安装版本的
`doctor`、`capability show`、对应 Host readback 和 versioned 文档判断。
### 从 `v0.5.4` 进入 `v1.0.0` Workspace
-`v1.0.0` 的产品里程碑是 Personal Workspace,而不是一次对所有 staged authority 或可选 Provider
-的整体提升。它把跨 Goal 总览、Agent lane、已完成任务、Capability 设置、verified reports、
+`v1.0.0` 的产品里程碑是 Personal Workspace。它把跨 Goal 总览、Agent lane、已完成任务、Capability 设置、verified reports、
Goal Channel 与桌面恢复汇集到一个 operator surface,同时保留 CLI、typed Kernel 与项目状态的
事实所有权。沿[1.0 Workspace 操作章](./workspace-v1.md)完成启动、readback、preview/apply/receipt、
配置与停用验收,再进入项目接入或开发者贡献主线。
@@ -260,5 +259,5 @@ live operation 不进入当前主线。需要这些能力时,应回到官方
覆盖面更宽:`loopx/host_loop_activation.py` 的 `SUPPORTED_AGENT_TYPES` 列出 21 个类型,其中 9 个
另有独立的 goal-mode 适配包(`claude_goal_mode`、`kunluncode_goal_mode`、`opencode_goal_mode`、
`pi_goal_mode`、`zcode_goal_mode`、`agy_goal_mode`、`dsh_goal_mode`、`kiro_cli_goal_mode` 等)。
-路线选择是教学取舍,不是能力边界:其余 harness 的接入差异,以各自适配包和
+路线选择是教学取舍:其余 harness 的接入差异,以各自适配包和
[协议文档](/loopx/docs/reference/protocols/) 为准。
diff --git a/docs/book/chapters/01-from-session-to-loop.md b/docs/book/chapters/01-from-session-to-loop.md
index 11065ba92a..cf319c361b 100644
--- a/docs/book/chapters/01-from-session-to-loop.md
+++ b/docs/book/chapters/01-from-session-to-loop.md
@@ -1,7 +1,5 @@
# 从一次会话到长程任务
-一个 Agent 能在当前会话里改代码、跑测试、解释结果,不代表它能可靠地拥有一项持续数天的工作。本章说明这个差别从哪里来,以及它为什么需要一个不在会话里的东西。
-
## 一个看起来很顺利的开头
假设你要给已有 CLI 增加 `--format json`:
@@ -56,7 +54,7 @@
| 哪个 Agent 拥有当前任务 | 重启或交接后,所有权无法从记忆里恢复 |
| 外部世界的当前状态 | 昨天读到的 CI 状态今天可能已经变了 |
-Host 可以持久保存 transcript,但旧对话本身不提供当前权限、验收或恢复状态。判据是接手者能否从明确的事实源重新核对这些信息,而不依赖原会话的隐含理解。
+判据是接手者能否从明确的事实源重新核对这些信息,而不依赖原会话的隐含理解。
## 执行面与控制面
@@ -76,7 +74,7 @@ Observation / receipt: 返回可验证结果
Control plane: 接受、拒绝或重规划
```
-**控制面不替代执行面。** LoopX 不写代码、不托管 Git、也不代替 CI。它让这些系统的结果能被一个跨 Turn 的工作生命周期消费——这正是 10:17 之后缺的那一环。
+它让这些系统的结果能被一个跨 Turn 的工作生命周期消费——这正是 10:17 之后缺的那一环。
## 三类长程任务为什么能共用同一控制面
@@ -100,7 +98,7 @@ LoopX 的控制合同不绑定某一种业务流程。仓库里的 Control-Plane
→ 重新计算 continue | wait | ask | replan | repair | terminal
```
-复用的是**生命周期不变量**,而非一段通用 prompt。Issue-Fix 理解 `CHANGES_REQUESTED`,Auto ML 理解 matched baseline,Auto Research 理解 holdout——这些领域含义属于 Capability 与 Domain State。而谁能 claim、是否可执行、何时再次唤醒、什么证据允许 writeback、Goal 能否终止,由同一套 Kernel 合同决定。
+复用的是**生命周期不变量**。Issue-Fix 理解 `CHANGES_REQUESTED`,Auto ML 理解 matched baseline,Auto Research 理解 holdout——这些领域含义属于 Capability 与 Domain State。而谁能 claim、是否可执行、何时再次唤醒、什么证据允许 writeback、Goal 能否终止,由同一套 Kernel 合同决定。
这条边界也解释了为什么新增领域能力不该复制一套 runner、queue、retry 和 completion 状态机。领域层提供可判定事实与 proposal,Provider 执行外部调用,Kernel 拥有跨领域生命周期。
@@ -108,7 +106,7 @@ LoopX 的控制合同不绑定某一种业务流程。仓库里的 Control-Plane
## 最小外置状态长什么样
-对上面的贯穿任务,最小状态不是完整 transcript,而是一组能回答恢复问题的事实:
+对上面的贯穿任务,最小状态是一组能回答恢复问题的事实:
```yaml
# 为解释而简化,不是 LoopX 文件格式
@@ -127,7 +125,7 @@ next_wake:
when: maintainer decision arrives
```
-这些字段的价值在于:**下一位执行者不必相信上一位 Agent 的自述**,而能从目标、工作队列、Gate、证据和 fresh environment 重新判断下一步。示例是解释模型,不是 LoopX 的存储格式。
+这些字段的价值在于:**下一位执行者不必相信上一位 Agent 的自述**,而能从目标、工作队列、Gate、证据和 fresh environment 重新判断下一步。示例是解释模型。
## 代价与边界:什么被放弃了
@@ -147,9 +145,9 @@ next_wake:
## 不变式
-1. **Prompt 内容不能独自证明持久写回。** 检查可寻址的记录、身份和版本,而不是窗口是否还开着。
+1. **Prompt 内容不能独自证明持久写回。** 检查可寻址的记录、身份和版本。
2. **执行面与控制面不能互相替代。** 控制面不写代码,执行面不决定自己是否合法。
-3. **复用的是生命周期不变量,不是 prompt。** 三个不同领域能共用一套控制面,靠的是这条。
+3. **复用的是生命周期不变量。** 三个不同领域能共用一套控制面,靠的是这条。
4. **下一位执行者不需要相信前一位的自述。** 如果需要,说明外置得不够。
接下来用[会话、Host Goal 与 LoopX](02-session-goal-loopx.md)判断任务需要哪层状态,再读[四个要求](02b-long-horizon-requirements.md),把这些问题组织成完整的架构视角。
diff --git a/docs/book/chapters/02-session-goal-loopx.md b/docs/book/chapters/02-session-goal-loopx.md
index 3ec5625b16..3038fc5ce8 100644
--- a/docs/book/chapters/02-session-goal-loopx.md
+++ b/docs/book/chapters/02-session-goal-loopx.md
@@ -78,9 +78,8 @@ Host 可以保存会话 transcript,也可以保存 native Goal 的 objective
| Executor / Agent | 当前 Turn 的推理、工具调用、bounded delivery 与验证 | 隐式长期记忆和越权批准 |
| LoopX control plane | Goal、Todo、Gate、quota、evidence lineage、recovery protocol | 模型推理、Git/CI 外部事实 |
-Dashboard、review packet 和 prompt 是 projection/interaction surfaces,不构成第五个
-authority。上一节说的"唤醒表面"就落在 Host 这一行:能不能把一个问题送到人面前,取决于
-Host 提供了什么,而不是取决于控制面写了什么。
+Dashboard、review packet 和 prompt 是 projection/interaction surfaces。上一节说的"唤醒表面"就落在 Host 这一行:能不能把一个问题送到人面前,取决于
+Host 提供了什么。
## 三种身份必须分开
@@ -92,7 +91,7 @@ LoopX 同时处理 Goal、Agent 和 Host,但三者回答的是不同问题:
| `agent_id` | 当前由哪个 peer/lane 承担工作? | 绑定 claim、Vision、quota 与 writeback;只有不存在已注册 lane 或显式 `--new-peer` 时新接入才默认注册 fresh identity |
| `host_surface` / runtime profile | 这一轮实际由哪个产品表面执行和唤醒? | 绑定 App heartbeat、visible Goal 或其他 host loop;必须按当前运行面显式声明 |
-已有 Goal 可以继续复用,不代表新 session 应接管已有 Agent identity。最新 Goal-start 合同要求:
+最新 Goal-start 合同要求:
1. 多个已注册 Goal 同时存在时,先返回只读 `goal_selection_gate`,再以精确 `--goal-id` 重跑;
2. 不根据相似的 objective、聊天摘要或目录名猜测 Goal;
@@ -103,15 +102,15 @@ LoopX 同时处理 Goal、Agent 和 Host,但三者回答的是不同问题:
才默认注册 fresh identity:`start-goal` 返回 `fresh_agent_registration_required`
(`register_fresh_agent`),首次接入无需额外 `--new-peer`;已绑定的 thread 沿用其绑定的 lane;
5. 只有用户明确要求接管某个已有 Agent,才以该精确 `agent_id` 继续;
-6. Agent 名称或前缀不证明 Host,实际运行面要由 host/runtime metadata 说明。
+6. 实际运行面要由 host/runtime metadata 说明。
这样,"继续同一个项目"与"冒充上一个执行者"不会被压成同一操作。
## 任务资格卡:先判断是否值得使用 LoopX
-LoopX 不是"任务越大越应该用"的同义词。先把任务写成一张可审查的资格卡:
+先把任务写成一张可审查的资格卡:
-这张卡是本书提供的决策工具,不是 LoopX CLI schema,也不会被 `start-goal` 自动写入状态。
+这张卡是本书提供的决策工具。
真正进入 LoopX 的 Goal、Todo、Gate、acceptance 和 boundary 仍以当前协议与 CLI 为准。
| 字段 | 要回答的问题 | 不满足时的默认选择 |
@@ -126,9 +125,9 @@ LoopX 不是"任务越大越应该用"的同义词。先把任务写成一张可
前四个字段直接对应第二段故事里的失败:`external_wait` 为真,说明这个任务会停在等待上;
`authority` 为真,说明这个等待必须由人给出决定。两项都满足时,"谁来唤醒那个人"就成了
-启动前必须回答的问题,而不是运行一段时间之后才发现的缺口。
+启动前必须回答的问题。
-满足一项不代表必须使用 LoopX。真正有价值的组合通常是:跨 session + 有外部等待或 handoff +
+真正有价值的组合通常是:跨 session + 有外部等待或 handoff +
有独立 acceptance,并且项目需要把 authority、evidence 和恢复条件外置。
### 如何比较普通会话、Goal 与 LoopX
@@ -211,10 +210,9 @@ Gate G
Goal 表达项目结果,Todo 表达可调度的工作单元。LoopX 可以为 Todo 记录优先级、依赖、claim、
lease、successor 和 handoff。Per-Agent Vision 则保存某个 peer 当前的 bounded role direction、
-acceptance summary 与 replan trigger;它是 per-Agent 的路线,也不是全局产品愿景。
+acceptance summary 与 replan trigger;它是 per-Agent 的路线。
-这使"目标仍 active"与"当前谁可以做哪件事"成为两个问题。Agent id 是工作身份,不证明 Host
-身份;`codex-*` 前缀也不能证明任务实际运行在 Codex App 还是 CLI。新 session 可以复用同一
+这使"目标仍 active"与"当前谁可以做哪件事"成为两个问题。Agent id 是工作身份。新 session 可以复用同一
Goal 的历史与 frontier,并在没有已注册 lane 或显式 `--new-peer` 时以 fresh Agent identity 进入;
已有 claim 则通过显式 takeover 或 handoff 处理。
@@ -260,7 +258,7 @@ Host 仍然拥有实际唤醒机制。LoopX 输出调度合同,不假装自己
### 5. 跨 Agent、跨 Host 与恢复
LoopX 的 canonical state 属于项目。Codex App、Codex CLI 或其他受支持 Host 可以读取同一个
-Goal 边界,而不是各自维护一份"当前进度"。
+Goal 边界。
```text
Codex App heartbeat ─┐
@@ -289,8 +287,7 @@ LoopX 保留同一 control-plane contract,但不同 Host 的启动和唤醒机
| DeepSeek Harness | native skill + same-session Driver / `loopx turn run-once` | 每段 bounded execution 仍需独立 validation |
| Shell / other Agent | guided packet + caller-owned runner | 无 runner hook 时由调用方唤醒 |
-这张表就是资格卡第二个维度的数据来源。表中出现一个 Host 不代表所有 Host 都支持相同
-automation API。`host_surface` 未知时,应省略一次该参数并使用只读 selection Gate;不要把
+这张表就是资格卡第二个维度的数据来源。`host_surface` 未知时,应省略一次该参数并使用只读 selection Gate;不要把
Codex CLI、IDE plugin、App SSH 或普通 shell 猜成 Codex App heartbeat。完整表面、启动方式、
停止策略和验证证据以 Runtime Connector Catalog 与对应 Host 文档为准;Dev Book 不复制每个
adapter 的完整 runbook。
@@ -311,8 +308,7 @@ LoopX control plane -> Codex Goal continuation -> Agent Turn
`---------- validated writeback -------'
```
-因此,Codex Goal 与 LoopX 的关系更像 Host lifecycle 与 project lifecycle 的组合,而不是两套
-互相替代的 Agent runtime。
+因此,Codex Goal 与 LoopX 的关系更像 Host lifecycle 与 project lifecycle 的组合。
## 代价与边界:引入一层状态买到了什么
@@ -337,7 +333,7 @@ evidence lineage。维护成本随任务数量增长,而它换来的是任务
**边界三:Host 表面决定哪些能力真的可用。** 资格卡判定的 `external_wait` 和 `handoff`,
只有在当前 Host 能唤醒、能推送、能回读时才会生效。缺少这些表面的 Host 上,正确的做法是
-缩小任务范围或换一个表面,而不是把任务升级上去期待它自己解决。
+缩小任务范围或换一个表面。
**边界四:控制面只为项目级问题存在。** 没有跨 session、没有外部等待、也没有交接的单次任务,
留在会话里更快。为了"更 Agentic"而制造状态,付出的就是上面的代价一。
@@ -356,7 +352,7 @@ Todo 阻塞得对,控制面每次 tick 都做出正确判断,而那个人从
lane 或显式 `--new-peer` 时以 fresh Agent identity 进入,这是合法路径。若推断出一个相似的 `goal_id`,或者直接接管旧
`agent_id`,得到的就是两个写入者对同一份"当前进度"的假设。
-对应的观察方式是读状态,而不是读 transcript:重启之后控制面还能说出任务停在哪、在等谁,
+对应的观察方式是读状态:重启之后控制面还能说出任务停在哪、在等谁,
以及下一步由谁执行。这三项是判断能否接手的基础,还需结合任务风险与维护成本决定是否值得接入。
## 不变式
diff --git a/docs/book/chapters/02b-long-horizon-requirements.md b/docs/book/chapters/02b-long-horizon-requirements.md
index af21a49c8b..58c587d17e 100644
--- a/docs/book/chapters/02b-long-horizon-requirements.md
+++ b/docs/book/chapters/02b-long-horizon-requirements.md
@@ -15,9 +15,9 @@
## 要求一:状态能脱离当前上下文
-接手者需要知道精确 PR、commit、已经验证的行为和未解决的决定,而不是只读“我刚才修好了”。聊天可以被保存并解释历史,但它的持久性不自动产生结构、新鲜度或当前授权。
+接手者需要知道精确 PR、commit、已经验证的行为和未解决的决定。聊天可以被保存并解释历史,但它的持久性不自动产生结构、新鲜度或当前授权。
-有影响的事实需要可寻址的来源、适用版本与读取入口。代价是维护这些记录;收益是换会话后可以重新判断,而不是凭记忆补齐缺失条件。读[状态章节](state-substrate.md)时,重点检查 source 与 display 在当前模式下分别是什么。
+有影响的事实需要可寻址的来源、适用版本与读取入口。代价是维护这些记录;收益是换会话后可以重新判断。读[状态章节](state-substrate.md)时,重点检查 source 与 display 在当前模式下分别是什么。
## 要求二:保留已知事实,也保留不确定性
@@ -31,13 +31,13 @@
两名 Agent 可以处理不同工作,也可能同时认为同一项工作归自己。Claim 表达责任,适用的 lease/fence 约束当前实例;二者都不能替代 Goal 边界、Gate scope、能力和工作区要求。
-Default legacy、soft claim 和 hard lease 有不同实施边界,不应从一个模式推广出全局独占保证。多 peer 也不意味着全 Goal 只有一个执行者。接管和并行必须落到具体 writer 和当前输入上,见[权限分层](work-graph-and-authority.md#authority-layers)。
+Default legacy、soft claim 和 hard lease 有不同实施边界,不应从一个模式推广出全局独占保证。接管和并行必须落到具体 writer 和当前输入上,见[权限分层](work-graph-and-authority.md#authority-layers)。
## 要求四:预算与观察约束无效重复
预算限制数量,但余额不能独自决定下一轮是否有意义。等待 CI 需要实际读取正确 revision;等待批准需要对应决定;没有可用 Host 的 next due 只是一个时间记录。
-Monitor 保存目标与观察关系;scheduler/backoff 安排后续时机;Host 或已接入事件通道实际执行。退避减少重复读取但可能增加发现延迟;replan 重新判断路线,不是更强的退避。内部 no-spend 不表示模型、工具或网络免费,详见[观察责任](04b-budget-and-admission.md#observation-owners)。
+Monitor 保存目标与观察关系;scheduler/backoff 安排后续时机;Host 或已接入事件通道实际执行。退避减少重复读取但可能增加发现延迟;replan 重新判断路线。内部 no-spend 不表示模型、工具或网络免费,详见[观察责任](04b-budget-and-admission.md#observation-owners)。
## 四条要求怎样协同
@@ -49,13 +49,13 @@ Monitor 保存目标与观察关系;scheduler/backoff 安排后续时机;Hos
→ 重新观察变化,再决定继续、改路或停止
```
-这是教学责任链,不是新的全局 API 顺序。单项机制不能保证目标成功;读者需要理解它们怎样为彼此提供依据,以及哪一种失败应回到哪一个 owner。
+这是教学责任链。单项机制不能保证目标成功;读者需要理解它们怎样为彼此提供依据,以及哪一种失败应回到哪一个 owner。
## 阅读路线与证据
**首次阅读**先进入[完整一轮](03-one-turn.md#running-turn),看 T1 怎样形成可接受结果;再回到[状态](state-substrate.md)和[权限](work-graph-and-authority.md#design-choice),理解支撑这轮工作的事实与写入者;随后读[恢复](04-runtime-boundaries.md)和[观察](04b-budget-and-admission.md)。这与导读中的主线相同,不要求先背状态机枚举。
-**替代路线**适合已有控制面经验的读者:先状态与权限,再读 Turn。状态机专题与附录供回查,不是接入前必须全部完成的课程。
+**替代路线**适合已有控制面经验的读者:先状态与权限,再读 Turn。状态机专题与附录供回查。
| 核对边界 | 协议入口 | 不由它单独证明 |
| --- | --- | --- |
diff --git a/docs/book/chapters/03-one-turn.md b/docs/book/chapters/03-one-turn.md
index 4c5c681897..af1989865d 100644
--- a/docs/book/chapters/03-one-turn.md
+++ b/docs/book/chapters/03-one-turn.md
@@ -1,6 +1,6 @@
# 一轮受治理的工作
-一轮工作的核心不是调用一次模型,而是把当前事实变成有边界的行动,再把结果交给对应 owner 验证和接受。本章先走正常路径,再处理三个容易混淆的情况:产物验证通过但尚未获准发布、已经写回但结算不完整,以及发现依赖后需要让其他工作继续。
+一轮工作的核心是把当前事实变成有边界的行动,再把结果交给对应 owner 验证和接受。本章先走正常路径,再处理三个容易混淆的情况:产物验证通过但尚未获准发布、已经写回但结算不完整,以及发现依赖后需要让其他工作继续。
## 用贯穿任务走完正常一轮 {#running-turn}
@@ -40,7 +40,7 @@ flowchart TD
| 允许向指定对象发布 | G1 | 有权决定者对对象、scope 和条件的明确决定 | 发布动作已经发生 |
| 交付到指定位置或接受者 | T3 | 产物版本、目标位置的实际读回,以及任务要求的接收确认 | 仅创建本地文件就完成了外部投递 |
-这是一张教学推理表,不是新增的验收 schema。当前 objective、acceptance、permissions 和 terminal conditions 分布在项目材料、Vision、Todo 与运行约束中;不能假装已有一个统一可写的 Goal intent 对象自动完成所有判断。实际存储与版本依据见[状态章节](state-substrate.md)和[状态机地图](core-state-machines.md)。
+这是一张教学推理表。当前 objective、acceptance、permissions 和 terminal conditions 分布在项目材料、Vision、Todo 与运行约束中;不能假装已有一个统一可写的 Goal intent 对象自动完成所有判断。实际存储与版本依据见[状态章节](state-substrate.md)和[状态机地图](core-state-machines.md)。
局部证据通过对应 lifecycle 入口被接受,才产生相应工作事实。随后还要检查依赖、未解决的决定、后继与目标验收。若任务只要求返回一份可审阅 patch,不能额外要求真实生产发布;若任务明确要求投递,则本地文件存在不够。**接受条件来自原任务与当前有效决定,不来自执行者为了宣告完成临时降低的标准。**
@@ -60,13 +60,13 @@ flowchart TD
**Decide** 读取当前 `interaction_contract` 和选中工作。旧 prompt、旧卡片或上轮建议不覆盖当前选择。
-**Act** 产生一个输入明确、范围有界、结果连贯的工作段。Bounded 不等于只改一行;一个能独立验证的功能切片比若干无法验收的零碎修改更有用。
+**Act** 产生一个输入明确、范围有界、结果连贯的工作段。一个能独立验证的功能切片比若干无法验收的零碎修改更有用。
**Validate** 检查后置条件:代码要验证行为,文档要核对命令和解释,外部效果需要相应系统的读回,blocker 也需要可核对的缺失条件。退出码只有在验证器确实检查了目标后置条件时才有意义。
**Write back** 由对应 owner 接受状态变化和紧凑证据引用。验证期间代码或 Todo 声明改变时,重新判断结果适用性;不能用针对旧声明的成功覆盖新状态。Todo completion 的锁内 snapshot 检查是其中一个具体边界,参见 [completion adapter](https://github.com/loopx-project/loopx/blob/76b7583a9f67d6090b43a8c6e58c42cb67a1f3c6/loopx/control_plane/todos/completion_transaction.py)。
-**Account** 根据本次结果的结算合同记账。LoopX quota 是内部预算 slot,不是供应商账单。Gate 通知、dry-run、未变化的观察和重复写回不能冒充新的 delivery spend;它们仍可能消耗时间、模型和网络资源。
+**Account** 根据本次结果的结算合同记账。LoopX quota 是内部预算 slot。Gate 通知、dry-run、未变化的观察和重复写回不能冒充新的 delivery spend;它们仍可能消耗时间、模型和网络资源。
缺验证时,不知道产物是否符合要求;缺写回时,后续读者不知道哪些结果被接受;投影滞后时,显示可能还停在旧状态;欠结算时,恢复对应记录而不是重做产物。不同缺口需要不同 owner,不能统一执行一次 `refresh-state` 就宣布全部修好。
@@ -80,7 +80,7 @@ host_execute → typed_result → validation
→ scheduler_apply → scheduler_ack
```
-`completed_phases` 必须满足对应合同的合法前缀约束。它约束可以声称完成的阶段,不证明进程只能在阶段间退出;Host 内部仍可能包含多个工具调用。TurnEnvelope 是 bounded projection,`turn plan` / `turn run-once` 是显式集成入口,不能推广成所有 Host 工具调用都受同一个 journal 管理。
+`completed_phases` 必须满足对应合同的合法前缀约束。它约束可以声称完成的阶段;Host 内部仍可能包含多个工具调用。TurnEnvelope 是 bounded projection,`turn plan` / `turn run-once` 是显式集成入口,不能推广成所有 Host 工具调用都受同一个 journal 管理。
对已 prepared 而未确认的 settlement step,恢复按原 effect identity 读取 provider:
@@ -104,7 +104,7 @@ host_execute → typed_result → validation
恢复后记录完整:settled
```
-在回执修复用例中,执行原响应返回的恢复命令得到 `appended=false`,扣减记录仍为一次。它证明该记录修复路径没有重复扣减,不证明外部服务免费或 Goal 已接受。故障注入只属于隔离测试;不要在真实项目里删除回执来“重现流程”。
+在回执修复用例中,执行原响应返回的恢复命令得到 `appended=false`,扣减记录仍为一次。它证明该记录修复路径没有重复扣减。故障注入只属于隔离测试;不要在真实项目里删除回执来“重现流程”。
从可信当前入口取得 `settlement_owed.command` 后,核对原 Goal、Agent、Todo、Turn 和 registry/runtime 绑定及权限。不要删参数,也不要执行任意日志中出现的命令。详细练习见[结算检查](12-control-plane-course.md#checkpoint-settlement)。
@@ -124,7 +124,7 @@ host_execute → typed_result → validation
该测试使用真实 CLI dispatch、TS 进程和 File/SQLite fixture。它断言同一 Turn 强行改绑得到 `heartbeat_receipt_identity_conflict`;原等待写回重放不重复记录,扣减为零;T1 仍为 open,等待条件未满足且验证摘要保留;新 Turn 才选中替代工作。它没有执行远端 CI,也没有证明每一种 Host 都用相同恢复入口。
-用户在旧版本遇到类似问题时,应保留原身份并查看本机实际提供的恢复动作;不得通过复制测试中的新字段或换 Todo 绕过。判断“是否等待”见[观察章](04b-budget-and-admission.md#wait-and-next-turn),而不是把收口与调度揉成一条规则。
+用户在旧版本遇到类似问题时,应保留原身份并查看本机实际提供的恢复动作;不得通过复制测试中的新字段或换 Todo 绕过。判断“是否等待”见[观察章](04b-budget-and-admission.md#wait-and-next-turn)。
## 尺度二:这一轮为什么获准?
@@ -142,7 +142,7 @@ identity
→ scheduler hint
```
-这是依赖关系的教学图,不是新的全局 first-match 表。实际优先级取决于当前入口和规则 owner。不能由“余额充足”“Goal active”或“另一个 Agent 很忙”推出本轮允许任意交付。
+这是依赖关系的教学图。实际优先级取决于当前入口和规则 owner。不能由“余额充足”“Goal active”或“另一个 Agent 很忙”推出本轮允许任意交付。
身份和来源不明时,不授予交付资格;scope 缺失时不能推断批准;独立工作不应被无关 Gate 冻结;有适用的恢复义务时不能用新交付掩盖原记录缺口。多个条件同时出现,先读最终 contract 与具名 reason,再追到负责的规则,不能让 Host 从零散计数重新拼一个决策。
@@ -154,7 +154,7 @@ identity
| Agent | 当前是否需要尝试工作,允许哪项 bounded action? |
| CLI | 需要哪些受控写回、结算或恢复动作? |
-G1 等待发布批准时,user channel 可以要求行动,agent channel 同时允许独立 T2。反之,“用户已看到提醒”不构成批准。`bounded_delivery`、`user_gate`、`scoped_user_gate_fallback`、`external_evidence_observation`、`monitor_quiet_skip`、`agent_scope_wait`、`autonomous_replan` 和 repair 等 mode 应结合当前 payload 阅读,不背成永远固定的枚举表。
+G1 等待发布批准时,user channel 可以要求行动,agent channel 同时允许独立 T2。`bounded_delivery`、`user_gate`、`scoped_user_gate_fallback`、`external_evidence_observation`、`monitor_quiet_skip`、`agent_scope_wait`、`autonomous_replan` 和 repair 等 mode 应结合当前 payload 阅读,不背成永远固定的枚举表。
Owner 在 Workspace 停止 Goal 属于相应生命周期,不应先由自动 Turn 的 quota 决定 owner 能否行使该权限。暂停也不抹去历史提交;是否允许某项恢复 mutation,仍由那条入口判断。完整组合 case 见 [Course 第 6 讲](/loopx/docs/development/control-plane-course/06-quota-decision-kernel/)。
@@ -162,7 +162,7 @@ Owner 在 Workspace 停止 Goal 属于相应生命周期,不应先由自动 Tu
已迁移的事务由 TypeScript owner 解释,Python 负责适配或明确的外部 effect。已知切片包括 Turn settlement、Todo completion、Host Todo settlement、spend/void/monitor-poll commit、本地 task-lease 完整生命周期、Vision refresh 与 receipt-bound scheduler follow-up。
-`v0.5.4` 仍提供 `turn plan` / `turn run-once`,这是历史迁移基线,不是当前发布版的替代标签,也不意味着“Python 已被移除”。[TypeScript Control-Plane Migration RFC](/loopx/docs/architecture/rfcs/typescript-control-plane-migration-v0/)解释 transaction-payoff 与 owner 边界。排查不一致时,找当前合同和实际调用路径,而不是一律相信某一种语言。
+`v0.5.4` 仍提供 `turn plan` / `turn run-once`,这是历史迁移基线。[TypeScript Control-Plane Migration RFC](/loopx/docs/architecture/rfcs/typescript-control-plane-migration-v0/)解释 transaction-payoff 与 owner 边界。排查不一致时,找当前合同和实际调用路径。
## 读回与本章的完成标准
diff --git a/docs/book/chapters/04-runtime-boundaries.md b/docs/book/chapters/04-runtime-boundaries.md
index 6b94f8adf6..2b28fe0869 100644
--- a/docs/book/chapters/04-runtime-boundaries.md
+++ b/docs/book/chapters/04-runtime-boundaries.md
@@ -2,7 +2,7 @@
上一章说明一轮怎样留下可接受的结果。本章把时间拉长:会话更换、代码更新、权限撤销、外部请求超时以后,哪些工作可以沿用,哪些判断必须重做,什么时候应改路或停止。
-恢复不是加载一段旧思维,而是重建**当前行动条件**。历史 transcript 可以按 Host 的规则保存并用于理解背景;它不是当前授权、有效验收或外部状态的替代品。恢复历史事实与批准下一次行动,始终是两个问题。
+恢复是重建**当前行动条件**。历史 transcript 可以按 Host 的规则保存并用于理解背景。恢复历史事实与批准下一次行动,始终是两个问题。
## 同一任务:响应丢失之后恢复哪一项 {#receipt-recovery}
@@ -28,7 +28,7 @@ sequenceDiagram
end
```
-图的第一条分支有“R1 确实存在且有效”的前提。只有错误输出而没有 provider 读回时,不能猜自己位于哪条分支。已确认 absent 后是否可以执行,仍取决于当前恢复合同、身份和授权,不是从缺失记录直接得到许可。
+图的第一条分支有“R1 确实存在且有效”的前提。只有错误输出而没有 provider 读回时,不能猜自己位于哪条分支。已确认 absent 后是否可以执行,仍取决于当前恢复合同、身份和授权。
R1 恢复后,继续读取 T3 的当前条件。C1 的提交成功不能验收 C2;T1 的结算也不能替代 G1 对发布的决定。
@@ -74,7 +74,7 @@ G1 是否仍覆盖 C2,取决于原决定绑定的对象和条件;不是所
**Retry / reconcile**:原意图仍成立,但需要确认或完成原操作。只对具有已核对幂等和恢复边界的操作重试;外部结果未知时,优先 reconcile / readback。`unknown` 不是失败的另一种拼写。
-**Replan**:工作含义需要改变,例如新证据推翻方案、验收改变、工作候选耗尽但目标未满足。它应产生当前协议接受的 Todo、Vision、successor、acceptance 关系变化或有据的终止结果,不是再写一遍计划。
+**Replan**:工作含义需要改变,例如新证据推翻方案、验收改变、工作候选耗尽但目标未满足。它应产生当前协议接受的 Todo、Vision、successor、acceptance 关系变化或有据的终止结果。
**Self-Repair**:目标工作可能仍然正确,但来源、投影、路由或回执链存在缺口。先定位 owner,再修具体缺口;不能把删 Gate、降低 validator 或清空历史当成修复。
@@ -82,28 +82,28 @@ Dreaming 产生候选方向或假设,不直接获得执行权。只有被当
## Material Evidence Delta:有活动不等于有进展
-设想一个教学案例:一天里不断改笔记、补无关测试、重排目录,却没有降低目标的任何验收缺口。每项产物可能真实存在,但这不足以说明整体收敛;这也不是声称当前规则会无条件允许无限次同类工作。
+设想一个教学案例:一天里不断改笔记、补无关测试、重排目录,却没有降低目标的任何验收缺口。每项产物可能真实存在,但这不足以说明整体收敛。
-Material Evidence Delta 关注新增的、能改变下一步判断的证据或状态,而不是只数 Turn、文件或字符。负面结果也可能有价值:排除一个假设、确认一个真实 blocker、缩小未知范围,都能改变后续路线。
+Material Evidence Delta 关注新增的、能改变下一步判断的证据或状态。负面结果也可能有价值:排除一个假设、确认一个真实 blocker、缩小未知范围,都能改变后续路线。
Delivery Batch Scale 描述改动范围;Delivery Outcome 描述成果与目标的关系。`multi_surface` 或 `implementation` 不自动意味着完成 Goal。`surface_only`、`outcome_gap`、`outcome_progress`、`primary_goal_outcome` 要按对应合同解释;执行者选择一个好看的标签不能替代证据。
### Vision checkpoint 与 baseline
-Vision 是 per-Agent 的执行路线,不是随手笔记。适用的 material refresh 需要说明路线被 patch、保持不变的依据、retired/superseded 的关系,或该角色为何不需要 Vision。
+Vision 是 per-Agent 的执行路线。适用的 material refresh 需要说明路线被 patch、保持不变的依据、retired/superseded 的关系,或该角色为何不需要 Vision。
-“保持不变”需要可比较的 baseline。没有 baseline 时先建立当前路线;不能把从未检查过写成没有变化。出现 `vision_checkpoint_missing` 等 gap 时,回到负责的 checkpoint 入口,补实际关系,而不是增加愿景 prose。不同 replan/repair 的优先级仍由当前 owner 决定,不把这段教学说明变成所有 Host 的全局规则表。
+“保持不变”需要可比较的 baseline。没有 baseline 时先建立当前路线;不能把从未检查过写成没有变化。出现 `vision_checkpoint_missing` 等 gap 时,回到负责的 checkpoint 入口,补实际关系。不同 replan/repair 的优先级仍由当前 owner 决定,不把这段教学说明变成所有 Host 的全局规则表。
### 六条收敛不变量
这六个问题用于检查完整性,不新增公共字段或一条自动通过算法:
1. **方向**:当前工作如何关联 Goal / Acceptance 与适用的 Vision?
-2. **权限**:正确主体是否在正确对象和 scope 上具有当前资格?能力存在不等于得到授权。
+2. **权限**:正确主体是否在正确对象和 scope 上具有当前资格?
3. **证据**:观察、验证与决定是否绑定正确输入和来源,仍满足新鲜度要求?
4. **Delta**:新增了什么可重读事实,或确认了哪项合法等待?
5. **活性**:未完成目标还有工作、可执行观察、决定、修复或明确停止责任吗?
-6. **终局**:后继、等待、回执与验收缺口是否按适用合同全部处理,而不是只看列表为空?
+6. **终局**:后继、等待、回执与验收缺口是否按适用合同全部处理?
安全避免错误推进,活性避免在缺少下一入口时永久卡住;二者都不保证任意目标必然成功。更多案例见[长程收敛专题](/loopx/docs/development/control-plane-course/topic-long-horizon-convergence/)和[证据与修复课程](/loopx/docs/development/control-plane-course/08-evidence-refresh-and-self-repair/)。
@@ -118,9 +118,9 @@ Vision 是 per-Agent 的执行路线,不是随手笔记。适用的 material r
→ 读回并重新判断依赖该结果的工作
```
-Legacy Markdown 可能仍是源;已选 canonical provider 的 Todo 不能从旧 Markdown 兜底。若源已提交但显示旧,修投影;若源本身错误,通过原 lifecycle 修正;若读取不可用,保留未知。让几个页面手工显示相同内容,不等于恢复了正确状态。
+Legacy Markdown 可能仍是源;已选 canonical provider 的 Todo 不能从旧 Markdown 兜底。若源已提交但显示旧,修投影;若源本身错误,通过原 lifecycle 修正;若读取不可用,保留未知。
-`refresh-state` 是受控写回,不是所有故障的通用查询。纯查看入口与 mutation 分开,参见[现场查阅](appendix-reference.md#read-before-change)。Workspace 操作回执与页面状态的具体比较见[暂停案例](workspace-v1.md#pause-readback)。
+`refresh-state` 是受控写回。纯查看入口与 mutation 分开,参见[现场查阅](appendix-reference.md#read-before-change)。Workspace 操作回执与页面状态的具体比较见[暂停案例](workspace-v1.md#pause-readback)。
## 停止、闭环与补偿
@@ -128,13 +128,13 @@ Goal 被 owner 停止、quota 暂停或 Host 退出,不能反证目标已完
若当前要求确实满足,按已有终局入口留下依据;若仍需工作,保留后继;若结果未知,保留观察或 blocker。被验证的负向结果和有覆盖依据的 no-follow-up 可以诚实结束一条路径,不需要伪造成功。
-已经生效的错误操作需要补偿,不是删除历史。[Rollback packet 协议](/loopx/docs/reference/protocols/rollback-packet-v0/)帮助表达影响对象、来源、恢复选择、批准与验证,但 packet 不是执行许可。Revert、fix-forward、外部清理和支持请求有不同前提;回滚安装也不必然逆转状态格式或远端效果。
+已经生效的错误操作需要补偿,不是删除历史。[Rollback packet 协议](/loopx/docs/reference/protocols/rollback-packet-v0/)帮助表达影响对象、来源、恢复选择、批准与验证。Revert、fix-forward、外部清理和支持请求有不同前提;回滚安装也不必然逆转状态格式或远端效果。
补偿完成后重新检查真实后置条件,并明确哪些结果仍需接受者确认。内部记录收口、收件人收到产物和整体验收是分开的,参见[第一份交付](05-connect-existing-project.md#first-delivery)。
## 恢复的代价与公开边界
-恢复依赖可读的原记录、可用的 provider 读回与当前权限。缺少它们时可能需要人工或外部支持,不能靠换身份推断问题消失。反复修投影的成本也应成为工程问题,而不是把“系统能自修复”当成持续故障的理由。
+恢复依赖可读的原记录、可用的 provider 读回与当前权限。缺少它们时可能需要人工或外部支持,不能靠换身份推断问题消失。反复修投影的成本也应成为工程问题。
证据采集消耗时间与资源,应与风险匹配;检查太少会漏掉变化,过度重复又可能吞噬交付。正文讨论的是如何保存最小充分证据,不要求把每段思考永久记录下来。
@@ -149,8 +149,7 @@ Goal 被 owner 停止、quota 暂停或 Host 退出,不能反证目标已完
- 写回时用 `--vision-unchanged-reason` 给出“不变”理由;LoopX 会自动把已有 vision 绑定为 baseline,
不需要另外传入 revision。
-如果 baseline 缺失但 agent 仍声称 unchanged,quota 会产生 `vision_checkpoint_missing` gap。这不是
-为了惩罚,而是为了防止 agent 在 never-checked 状态上积累错误假设。完整失败回放见
+如果 baseline 缺失但 agent 仍声称 unchanged,quota 会产生 `vision_checkpoint_missing` gap。为了防止 agent 在 never-checked 状态上积累错误假设。完整失败回放见
[Control-Plane Course 第 8 讲](/loopx/docs/development/control-plane-course/08-evidence-refresh-and-self-repair/)。
## Terminal Closure
@@ -182,7 +181,7 @@ required external readbacks are fresh
| Capability | 定义 caller outcome,规范 Provider 输出,应用 domain policy |
| LoopX Kernel | 接受或拒绝 proposal,拥有通用 Goal/Todo/Gate/Quota/Recovery state |
-正常流向不是“Agent 调工具后直接写完成”:
+正常流向:
```text
Agent -> Capability -> Provider -> external system
@@ -296,5 +295,5 @@ LoopX 不替代:
Capability/Domain State、Provider、Host/Runner、Projection/Dashboard、Docs/fixtures 或
Extension。
-Extension 是开发者贡献中的独立 packaging/lifecycle 路径,不是所有贡献的统一抽象。两条主线共享
+Extension 是开发者贡献中的独立 packaging/lifecycle 路径。两条主线共享
同一控制面模型,但不互相要求。下一部分先从最常见的项目接入开始。
diff --git a/docs/book/chapters/04b-budget-and-admission.md b/docs/book/chapters/04b-budget-and-admission.md
index ea01234d0f..d6814e0529 100644
--- a/docs/book/chapters/04b-budget-and-admission.md
+++ b/docs/book/chapters/04b-budget-and-admission.md
@@ -1,6 +1,6 @@
# 消耗的上限与外部观察
-T1 完成后,M1 仍在等待 C1 的 CI,G1 仍在等待发布决定。预算还有余额,不代表应该反复调用模型;没有新消息,也不证明外部条件没有变化。本章把“是否行动”“何时再看”“谁去观察”与“何时改路”分开,再让它们共同支持一次可解释的等待。
+T1 完成后,M1 仍在等待 C1 的 CI,G1 仍在等待发布决定。预算还有余额,不代表应该反复调用模型。本章把“是否行动”“何时再看”“谁去观察”与“何时改路”分开,再让它们共同支持一次可解释的等待。
## 先区分五种责任 {#observation-owners}
@@ -16,7 +16,7 @@ T1 完成后,M1 仍在等待 C1 的 CI,G1 仍在等待发布决定。预算
## 一个错误计数策略会怎样误导判断
-以下是**假设性的错误策略**,不是声称当前实现仍有此缺陷:把“最近连续没有变化”只记在一个全局目标上,每次换目标就清零。
+以下是**假设性的错误策略**:把“最近连续没有变化”只记在一个全局目标上,每次换目标就清零。
| 时间 | 到期工作 | 正确的工作项事实 | 假设的错误全局判断 |
| --- | --- | --- | --- |
@@ -25,7 +25,7 @@ T1 完成后,M1 仍在等待 C1 的 CI,G1 仍在等待发布决定。预算
| 11:00 | M1 | M1 第二次无变化 | 又换目标,重新计数 |
| 11:30 | M1、M2 各自到期 | 分别更新自己的观察 | 结果取决于处理顺序,而非目标真正停滞多久 |
-错误不在阈值太高,而在于把不同目标的观察混成了一段历史。修正应保留每个 Monitor 自己的身份和计数,而不是不断降低阈值。相反,假如根本没有可用 Host 去执行 due observation,计数器再正确也只是一份静态记录:这是执行活性缺口,不是 no-change。
+错误不在阈值太高,而在于把不同目标的观察混成了一段历史。修正应保留每个 Monitor 自己的身份和计数。相反,假如根本没有可用 Host 去执行 due observation,计数器再正确也只是一份静态记录:这是执行活性缺口,不是 no-change。
## 等 CI 时,观察频率怎样选择 {#running-wait}
@@ -51,7 +51,7 @@ Monitor 保存调用者完成的观察。本身不访问 CI,`next_due_at` 也
正常交付仍受预算限制:当前窗口 `spent_slots >= allowed_slots` 时会进入相应 throttling。余额不足不能通过换 Todo 或把交付叫作观察绕过;余额充足也不能绕过 Gate、当前身份、能力、工作区和依赖。
-读取最终 contract,至少区分“允许交付”“需要恢复或修复”“观察”“等待”与“要求决定”。身份不明时拒绝交付资格,不等于整个诊断过程不消耗任何资源。`quota should-run --codex-app` 的相关准入路径可能创建 heartbeat receipt,不应当作无副作用的循环查询。现场读取见[附录](appendix-reference.md#read-before-change)。
+读取最终 contract,至少区分“允许交付”“需要恢复或修复”“观察”“等待”与“要求决定”。身份不明时拒绝交付资格。`quota should-run --codex-app` 的相关准入路径可能创建 heartbeat receipt,不应当作无副作用的循环查询。现场读取见[附录](appendix-reference.md#read-before-change)。
内部记账回答已接受的工作如何归因;scheduler cadence change、Gate 通知、dry-run、未变化的 poll、重复写回不能冒充新的 delivery spend。不要用“无费轮次”描述 no-spend,否则会掩盖观察本身的资源成本。
@@ -61,11 +61,11 @@ T1 发现真实依赖时,等待需要有具体对象,例如 `monitor_changed
工作图中存在独立 T2,并不意味着已绑定 T1 的当前 Turn 可以直接改绑。应先完成原 Turn 按其合同要求的等待写回和收口,再由后续准入选择新工作。**Turn 收口、Todo 等待与下轮选择是三件事。**
-[Turn 章的等待时序](03-one-turn.md#wait-closeout)用主线 `f49b4a00…` 的明确测试解释这条路径,并标注了它不属于旧发布版承诺。它验证不重复扣减、不强迫执行 Monitor poll、原 Todo 的等待和验证声明仍保留;不是一条适用于所有 Host 的全局调度顺序。
+[Turn 章的等待时序](03-one-turn.md#wait-closeout)用主线 `f49b4a00…` 的明确测试解释这条路径,并标注了它不属于旧发布版承诺。它验证不重复扣减、不强迫执行 Monitor poll、原 Todo 的等待和验证声明仍保留。
## Cadence backoff 与路线重规划
-Backoff 问的是“相同条件下,多久以后再观察”。它从已仲裁的 decision 和运行 profile 派生调度建议,并按对应 scheduler state 的 identity / `reset_token` 保持或重置退避。具体间隔、上限与 unchanged limit 应读取当前 profile,而不是把一组示例数值当作所有 Host 的共同协议。
+Backoff 问的是“相同条件下,多久以后再观察”。它从已仲裁的 decision 和运行 profile 派生调度建议,并按对应 scheduler state 的 identity / `reset_token` 保持或重置退避。具体间隔、上限与 unchanged limit 应读取当前 profile。
如果没有事件通道,外部变化只能在下一次真实观察后被发现。reset 可以改变后续间隔,但不会追回已经等待的时间。Host apply 成功或已经匹配目标 cadence 后,才按绑定 ACK 路径确认;失败或超时要记录对应失败,不能伪造 ACK。详见[调度入口](appendix-reference.md#scheduler-entry)。
@@ -78,9 +78,9 @@ Replan 问的是“继续等待是否仍符合目标,是否有更好的下一
| 只有 peer 有工作 | 不以 peer 的进展抹掉当前 Agent 的停滞 |
| Monitor 明确为 `watch_only` | 相关测试中即使计数很大,也不因此触发这项 replan |
-[策略测试](https://github.com/loopx-project/loopx/blob/76b7583a9f67d6090b43a8c6e58c42cb67a1f3c6/tests/control_plane/test_monitor_replan_agent_scope.py)中的阈值为 5。这是被测策略,不是所有等待必须改路的普遍定理。测试预置计数后检查 decision;它不证明真实交错 poll、并发计数写入或真实 Host 唤醒。更完整的预测练习见[Monitor 检查](12-control-plane-course.md#checkpoint-monitor)。
+[策略测试](https://github.com/loopx-project/loopx/blob/76b7583a9f67d6090b43a8c6e58c42cb67a1f3c6/tests/control_plane/test_monitor_replan_agent_scope.py)中的阈值为 5。这是被测策略。测试预置计数后检查 decision。更完整的预测练习见[Monitor 检查](12-control-plane-course.md#checkpoint-monitor)。
-因此,replan 不是“更强的 backoff”。一次可以改变观察频率,另一次需要重新判断路线并形成当前协议认可的结果;仅写“重新想过了”不能替代所需的变化或明确终止依据。
+一次可以改变观察频率,另一次需要重新判断路线并形成当前协议认可的结果;仅写“重新想过了”不能替代所需的变化或明确终止依据。
## 怎样定义一项可解释的观察
diff --git a/docs/book/chapters/05-connect-existing-project.md b/docs/book/chapters/05-connect-existing-project.md
index 98a8d63a29..ca905fcd8d 100644
--- a/docs/book/chapters/05-connect-existing-project.md
+++ b/docs/book/chapters/05-connect-existing-project.md
@@ -5,7 +5,7 @@
沿用[贯穿任务](00-reading-guide.md#running-example):A 实现兼容的 JSON 输出 T1,B 补文档 T2,
M1 观察 CI,G1 保留维护者的 schema/发布决定,T3 在条件满足后交付。
-这是合成教学任务,不是已经运行成功的项目记录。命令使用你的真实项目与当前 packet;
+这是合成教学任务。命令使用你的真实项目与当前 packet;
T1、M1、C1 等代号不是 CLI id,也不能当作 API payload。
!!! tip "快速阅读路线"
@@ -16,7 +16,7 @@ T1、M1、C1 等代号不是 CLI id,也不能当作 API payload。
## 先分清三个完成点 {#three-completions}
-安装完成、接入完成、工作完成不是同一句话。安装回答 CLI 与所需 runtime 是否可用;
+安装回答 CLI 与所需 runtime 是否可用;
接入回答工作归属、状态位置与运行路径是否明确;交付回答实际产物是否满足当前验收。
接入成功可以暂时没有执行中的 Turn;一轮成功也可以仍在等待外部检查或批准。
@@ -30,14 +30,14 @@ T1、M1、C1 等代号不是 CLI id,也不能当作 API payload。
`.loopx/registry.json` 与 `.loopx/goals//ACTIVE_GOAL_STATE.md`);`loopx status` 能显示
active state 与当前 frontier;再次连接按精确 `goal_id` 复用已有 Goal 而不是覆盖;新接入的执行者使用
fresh `agent_id`,除非用户明确授权 takeover;`.loopx/` 与 `.loopx/goals/` 不进入 Git。这些本地状态
-是控制面状态,不是项目源码。
+是控制面状态。
-因此,本章不是把所有命令连成一段可以盲目粘贴的脚本。读取、预览和执行分段进行,
+读取、预览和执行分段进行,
每次只在前一步给出足够依据后继续。出现拒绝时先理解所保护的条件,不为让教程跑通而绕过检查。
## 一、准备:确认项目,保护已有状态 {#prepare-project}
-从你准备管理的 Git 项目根目录开始,不是从 LoopX 的源码目录开始。在目标仓库根目录打开你正在使用的 Agent 开发工具,把下面提示词中的目标和 Host 改成自己的
+从你准备管理的 Git 项目根目录开始。在目标仓库根目录打开你正在使用的 Agent 开发工具,把下面提示词中的目标和 Host 改成自己的
情况后直接发送:
```text
@@ -74,7 +74,7 @@ fresh `agent_id`,除非用户明确授权 takeover;`.loopx/` 与 `.loopx/goa
明确写“尚未接入完成”。
```
-这份提示词不是把控制权交给 Agent。它把可执行工作委托给 Agent,同时把以下决定留给你:
+它把可执行工作委托给 Agent,同时把以下决定留给你:
- 多个 Goal 中选择哪一个;
- 是否 takeover 已有 Agent identity;
@@ -142,7 +142,7 @@ git ls-files .loopx .loopx/goals .local
项目可能已经包含 `.loopx/registry.json` 或 `.loopx/goals/`。先识别已有 Goal、在途工作和状态位置,
不要复制其他项目的 registry,也不要为了得到一个空白起点覆盖旧状态。
-下面是常见布局示意,不是所有 authority、租约和日志的完整物理位置:
+下面是常见布局示意:
```text
your-project/
@@ -181,7 +181,6 @@ git check-ignore -v .loopx/goals/example/ACTIVE_GOAL_STATE.md
默认情况下已跟踪文件不受忽略规则支配;`--no-index` 用于不考虑 index 而诊断规则,
不是“强制忽略”,也不是专门处理尚不存在的文件。
`ls-files` 默认显示当前 index 中的路径;有输出说明路径被跟踪或暂存,**不单独证明已经推送**。
-没有输出也不证明旧提交或远端从未包含敏感材料。
依据见 [Git check-ignore](https://git-scm.com/docs/git-check-ignore) 与
[Git ls-files](https://git-scm.com/docs/git-ls-files)。
@@ -215,7 +214,7 @@ loopx doctor
已有 pip、pipx 或 archive 安装则按[附录升级说明](appendix-reference.md)确认安装 owner,
不要在不清楚来源时叠加另一个安装。
-`doctor` 比 `command -v loopx` 多回答依赖、安装和集成状态,但不是所有 Host 路径都已验证的证明。
+`doctor` 比 `command -v loopx` 多回答依赖、安装和集成状态。
需要验证实际 Effect runtime 与 journal checkpoint 路径时再使用:
```bash
@@ -245,9 +244,9 @@ loopx registry
loopx status
```
-对于已有项目,应先读取当前连接,按现有路径续接,而不是为了重试一项任务重复连接。
+对于已有项目,应先读取当前连接,按现有路径续接。
`connect` / `bootstrap` 登记 Goal 并写 active state;首连不会替调用方生成一套 onboarding Todo。
-没有可执行工作时,下一步是确认实际任务与工作边界,不是凭空增加配额。
+没有可执行工作时,下一步是确认实际任务与工作边界。
### Guided packet 是计划,不是执行回执
@@ -258,7 +257,7 @@ loopx start-goal --guided --project . \
--goal-text "增加兼容的 JSON 输出,保留默认文本输出;验证和文档完成后交付,不自动发布"
```
-返回的是 guided transaction packet。预览成功不证明 Todo 已写、Agent 已注册或 Host 已启动。
+返回的是 guided transaction packet。
读取 packet 当前要求补齐的选择,按照其提供的精确命令继续;不要从旧对话恢复一条已过时的执行指令。
存在多个 Goal 时,在 `goal_selection_gate` 的 choices 中选择精确 `goal_id`;目标文本相似不能作为
@@ -281,7 +280,7 @@ true,`global_sync.ok` 为 true,且 `registration_readback.verified` 为 true
### Host 选择不是能力授予
-已知实际 Host 时显式传入;以下二选一,不是依次激活两个 Host:
+已知实际 Host 时显式传入;以下二选一:
```bash
# Codex App
@@ -299,7 +298,6 @@ loopx start-goal --guided --project . \
不要用一个熟悉的名称代替探测。具体激活与读回分别见 [Codex App](06-codex-app.md) 和
[Codex CLI](07-codex-cli.md),其他适配器见 [Runtime Connector Catalog](/loopx/docs/integrations/runtime-connector-catalog/)。
类型注册、当前可启动、进程内自主继续、进程退出后可再次唤醒,是不同条件。
-一个参数被接受不证明这些条件都已成立。
## 四、接入验收:现在可以进入哪一步? {#connection-acceptance}
@@ -314,8 +312,7 @@ git status --short
git ls-files .loopx .loopx/goals .local
```
-它们不请求完成 Todo 或扣减交付配额,但“读取”不承诺整个进程完全无 IO:
-可能涉及 runtime 启动等支持动作。若环境有严格隔离要求,应按所用入口、provider 和设置单独确认。
+它们不请求完成 Todo 或扣减交付配额。若环境有严格隔离要求,应按所用入口、provider 和设置单独确认。
不要把所有名称带有“检查”的命令归入同一种无副作用类别。
准备进入本轮时,使用当前 Host 规定的准入路径,例如:
@@ -327,7 +324,7 @@ loopx quota should-run --goal-id --agent-id
读取完整 interaction contract、selected Todo、权限、workspace 与后续指令,不能只取一个
`should_run` 布尔值。尤其 `--codex-app` 的相关准入路径可以创建 heartbeat receipt;
它与单纯列举现状不同,不应在诊断脚本中无限重复。
-`refresh-state`、获取/续租、结算和 scheduler ACK 也都是各自有条件的操作,不是通用查询。
+`refresh-state`、获取/续租、结算和 scheduler ACK 也都是各自有条件的操作。
| 四问 | 接入验收需要的答案 |
| --- | --- |
@@ -341,11 +338,11 @@ loopx quota should-run --goal-id --agent-id
> 项目连接与身份已读回,私有状态未进入当前 index。Host 激活尚未确认,所以只完成接入准备,
> 还没有第一次执行。下一步按 CLI 章节中的当前 activation packet 启动并读回;不会宣称 T1 已交付。
-这是一份本地操作报告的**教学示意**,不是产品返回类型。对外分享时去掉私有路径、目标内容和凭据。
+这是一份本地操作报告的**教学示意**。对外分享时去掉私有路径、目标内容和凭据。
## 五、从接入走到第一份交付 {#first-delivery}
-完成 Host 章节后回到这里。目标不是让界面显示“正在运行”,而是完成一个足以独立验证的小工作段。
+完成 Host 章节后回到这里。目标是完成一个足以独立验证的小工作段。
不要把本节的推演称为真实 Host 的端到端测试;实际验收必须来自自己的运行结果。
### 第一幕:让 A 做 T1,而不是让它拥有整个发布流程
@@ -381,8 +378,8 @@ G1 没有批准发布时,T3 不能因 CI 通过或 T1 已结算而获得权限
可以在自身约束满足后继续。用户需要回答问题与 Agent 可以继续另一项工作可以同时成立。
具体判断见[观察与调度](04b-budget-and-admission.md)和[工作图](work-graph-and-authority.md)。
-无变化的观察不应冒充交付;它仍可能有计算和网络成本。没有收到通知也不是外部世界没有变化的证据。
-若 Host 已退出且没有可用唤醒机制,应报告运行缺口,而不是把 quiet 状态解释为健康等待。
+无变化的观察不应冒充交付;它仍可能有计算和网络成本。
+若 Host 已退出且没有可用唤醒机制,应报告运行缺口。
### 第四幕:条件改变,更新受影响的判断
@@ -391,7 +388,7 @@ G1 没有批准发布时,T3 不能因 CI 通过或 T1 已结算而获得权限
对象、scope 与条件,不能只看“approved”这个词。
若维护者同时修改了目标或验收,应走已有 planning/replan 和决定入口,将变化与当前工作关联。
-书中的 C1/C2 是解释适用性的例子,不是在声明已有一个统一的 Goal intent-version schema。
+书中的 C1/C2 是解释适用性的例子。
修改目标的权限不能由 Agent 为了凑齐“完成”而自行产生。
### 第五幕:把结果返回给需要验收的人
@@ -403,7 +400,7 @@ T3 的当前条件均有证据后,重新判断下一步。交付一个可审
以及接下来由谁决定或行动。链接到了产物、工作内部已结算、收件人实际得到结果、Goal 已接受,
这些事实分别核对,不能把其中任一项自动提升为全部完成。
-下面是本地交付报告的示意,而不是额外持久化格式:
+下面是本地交付报告的示意:
> JSON 输出与文档已在 C2 完成;列出的兼容检查及 C2 的 CI 支持当前实现结论。
> 已有工作写回与结算可追溯。维护者的发布决定仍未完成,因此返回待审阅产物,不执行发布。
@@ -414,7 +411,7 @@ T3 的当前条件均有证据后,重新判断下一步。交付一个可审
## 六、让 Agent 帮你接入,但不给它猜测权限 {#delegate-onboarding}
-可以把以下提示交给已在项目里工作的 Agent。它是委托示例,不是机器强制执行的新协议。
+可以把以下提示交给已在项目里工作的 Agent。它是委托示例。
已有明确授权的普通操作可按其范围完成,不要求每个命令都再次打断用户;身份接管、权限扩大、
外部发布和破坏性操作不能从模糊目标中推断出来。
diff --git a/docs/book/chapters/06-codex-app.md b/docs/book/chapters/06-codex-app.md
index 5725534d8f..683c5a322b 100644
--- a/docs/book/chapters/06-codex-app.md
+++ b/docs/book/chapters/06-codex-app.md
@@ -50,8 +50,7 @@ Agent Turn no delivery
validate -> writeback -> optional spend
```
-右分支是合法结局,而且是经常发生的那一种。它只说明**这一次**没有该做的工作,不等于 Goal
-frontier 已经收尾:已结算 Turn 的回放会返回 `should_run=false`,同时保留当前 cadence,等新的
+右分支是合法结局,而且是经常发生的那一种。它只说明**这一次**没有该做的工作:已结算 Turn 的回放会返回 `should_run=false`,同时保留当前 cadence,等新的
Turn identity 再评估。所以频繁走到右分支并不说明 cadence 该放慢;只有当前 `scheduler_hint`
提出调整(`apply_needed=true`)时,才按下面的四步执行。
@@ -94,8 +93,7 @@ Codex 当前通过 command-facade skill 暴露 LoopX;不要假设用户自定
第 5 步和第 7 步的顺序容易搞反。先激活 heartbeat 意味着你在 Todo 成型之前就开始被定时唤醒,每次
唤醒都会拿到一个还没有 frontier 的 Goal。先写 Todo 再激活,第一轮唤醒就有确定的候选。
-你不需要手工执行所有内部命令,但应该能从 Agent 报告中看到这些状态转换。得到一段自然语言计划,
-不等于项目状态已经建立;看到 guided packet,也不等于 heartbeat 已经安装。这两件事都要单独 readback。
+你不需要手工执行所有内部命令,但应该能从 Agent 报告中看到这些状态转换。这两件事都要单独 readback。
## 每一轮仍然要过 Quota Gate
@@ -150,8 +148,7 @@ loopx quota scheduler-ack-current
这里最容易漏掉的是 readback。应用了 `recommended_rrule` 就当作完成,是一种常见做法:本地 ACK
ledger 里有了记录,cadence 看起来生效了。但 ledger 记下的是**提议**,Host 上真正生效的**实际值**要单独读回。两者
不一致时,packet 会在 `scheduler_hint.app_automation.stateful_backoff.host_observation.status`
-上报 `drift_detected`,这时真实 cadence 和 ledger 已经分叉,必须按当前 hint 修复,而不是信任那份
-看起来完整的记录。
+上报 `drift_detected`,这时真实 cadence 和 ledger 已经分叉,必须按当前 hint 修复。
反向的组合也存在。当 `apply_needed=false, ack_needed=true` 时,精确 Host readback 已经匹配目标
cadence,应当跳过这次 no-op update 并直接执行绑定 ACK。把它当成"没事可做"会留下一条未结算的
@@ -173,12 +170,12 @@ readback 中表现为 `drift_detected`。
这是一条需要 readback 才能闭合的链路,不像本地写一个变量那样即时。
**代价三:空转与工作在图上看不出区别。** 两者都留下触发记录、都以成功退出。要区分它们,必须看
-writeback 和 spend 历史,而不是看 heartbeat 日志。
+writeback 和 spend 历史。
**边界一:heartbeat 不创造 frontier。** 一个没有 Todo 的 Goal 不会因为被频繁唤醒而出现下一步。
App 能保证有人看,不能保证有东西可做;没有可运行候选时就该进入 wait 或 monitor,让 cadence 放慢。
-**边界二:automation 不是第二控制面。** 不要在 automation prompt 里复制 quota 状态机,也不要让
+不要在 automation prompt 里复制 quota 状态机,也不要让
它自己解析 Todo 是否 runnable。稳定 prompt 只负责协议,判断属于每次读到的 packet。
**边界三:切换 Host 要核对工作归属。** App 和 CLI 可以读同一 Goal;切换前应查清旧实例是否仍执行、claim/lease 由谁持有,以及当前 writer 的围栏模式。需要显式移交时走对应 lifecycle,不能仅凭新 Host 已启动就并发推进同一项工作。
@@ -222,8 +219,7 @@ loopx start-goal --guided --project . \
### heartbeat 频繁空跑
-查看 `scheduler_hint`、monitor Todo 和 spend history。无变化的外部等待应转为 monitor/backoff,
-而不是每次启动完整 Agent Turn。若 RRULE 已放慢但触发频率没变,检查 `host_observation.status`
+查看 `scheduler_hint`、monitor Todo 和 spend history。无变化的外部等待应转为 monitor/backoff。若 RRULE 已放慢但触发频率没变,检查 `host_observation.status`
是否报告 `drift_detected`,并按当前 hint 重新 apply 与 ACK。
### Goal 被 Gate 阻塞
@@ -235,15 +231,15 @@ Gate 而不重复同样的安静轮询;若 Host cadence 更新失败而留下
## 不变式
-1. **heartbeat 触发不等于工作发生。** 判断真实性看 writeback 与 spend,不看触发次数。
+1. 判断真实性看 writeback 与 spend,不看触发次数。
2. **每次唤醒都过一次 `quota should-run`。** 没有这层 Gate,automation 就变成绕过决策的旁路。
3. **`should_run=false` 是合法结果,但它只关闭这一个 Turn。** 已结算回放保留当前 cadence,用新的
Turn identity 重新评估;`false` 的次数或本 Turn 的 receipt 都不能当作放慢 cadence 的依据。需要
放慢时,由当前 `scheduler_hint` 提出(`apply_needed=true`),再走第 4 条的四步。
4. **cadence 变化的四步缺一不可**:proposal、host apply、host readback、ACK。
-5. **本地 ACK ledger 不证明 Host 状态。** 只有 Host readback 与目标一致才闭合,不一致时按
+5. 只有 Host readback 与目标一致才闭合,不一致时按
`drift_detected` 修复。
6. **切换 Host 需要明确接管。** 同一 Goal 可被多处读取,写入仍须满足当前 authority、claim/lease 与围栏要求。
-这六条指向同一件事:定时唤醒买到的是**持续尝试的能力**,不是**持续进展的事实**。区分这两者,
+这六条指向同一件事:定时唤醒买到的是**持续尝试的能力**。区分这两者,
就是本章要求四的全部内容。
diff --git a/docs/book/chapters/07-codex-cli.md b/docs/book/chapters/07-codex-cli.md
index 57278e5d41..fc899618d2 100644
--- a/docs/book/chapters/07-codex-cli.md
+++ b/docs/book/chapters/07-codex-cli.md
@@ -4,7 +4,7 @@
## 为什么 active Goal 与后台唤醒不同
-假设修复还未完成,你结束了当前 Codex 进程。再次打开终端时,工作没有继续。这说明执行环境已经离开,不代表 native Goal 在进程存活时每轮都需要用户发消息。
+假设修复还未完成,你结束了当前 Codex 进程。再次打开终端时,工作没有继续。这说明执行环境已经离开。
| Host 状态 | 当前路径的行为 | 用户需要判断什么 |
| --- | --- | --- |
@@ -91,8 +91,7 @@ loopx quota should-run \
--runtime-profile codex_cli
```
-你应该看到 Host runtime 指向 `codex_cli`,scheduler owner 属于 Goal/agent loop,而不是 Codex App
-heartbeat。这个区别决定了"该唤醒时谁负责唤醒":如果 packet 报告 scheduler context 缺失,先修复
+你应该看到 Host runtime 指向 `codex_cli`,scheduler owner 属于 Goal/agent loop。这个区别决定了"该唤醒时谁负责唤醒":如果 packet 报告 scheduler context 缺失,先修复
runtime profile,不要忽略 warning。scheduler context 缺失或矛盾时,`scheduler_hint` 返回
`repair_scheduler_execution_context`,并把 unchanged poll 设为 `stop_until_context_repaired`:在修复
runtime profile 之前,它不会提出新的 cadence,也不会替你安排下一次唤醒。
@@ -110,7 +109,7 @@ lane 时,沿用该绑定。只有 Goal 没有任何已注册 lane 或显式 `-
lane,工作归属就被静默改写了。显式传入后,未注册的 id 会被拒绝;与 thread 绑定不同的已注册 id
会被当作明确的覆盖选择,所以只在确实要换 lane 时这样做。
-Agent identity 表达 LoopX 工作 lane,不证明具体 Host。判断工作是否真的在 Codex CLI 运行,要看
+判断工作是否真的在 Codex CLI 运行,要看
`host_surface`、runtime profile 或对应 run metadata。
交接时的正确顺序是:
@@ -155,13 +154,12 @@ Agent identity 表达 LoopX 工作 lane,不证明具体 Host。判断工作是
### 误用了隐藏 worker
停止该 worker,检查它是否写回了新 evidence 或 lease。先恢复 Todo ownership,再回到 visible
-TUI;不要让两个执行者并发修改同一工作树。检查这件事时要看 claim 与 lease 的实际归属,而不是看你
-记忆中谁在跑。
+TUI;不要让两个执行者并发修改同一工作树。检查这件事时要看 claim 与 lease 的实际归属。
### Goal 无变化轮询
达到 unchanged limit 后,Goal 应阻塞或安静等待。外部状态观察应转成 monitor Todo;用户通过
-Host 的 Goal resume 表面恢复,而不是反复重发完整任务。反复重发会让同一轮工作看起来像多轮进展。
+Host 的 Goal resume 表面恢复。反复重发会让同一轮工作看起来像多轮进展。
### App 与 CLI 同时激活
@@ -172,7 +170,7 @@ Host 的 Goal resume 表面恢复,而不是反复重发完整任务。反复
1. **区分 active、blocked 与进程退出。** 活跃 native Goal 可以继续;blocked 后按 Host resume 合同处理,退出后不能假定存在定时唤醒。
2. **setup Turn 只建立连接。** 连接和交付混在一轮里,后续每一步都建立在一个未审的计划上。
3. **`/goal` body 保持稳定。** 动态 Todo、Gate 和能力来自当次 decision packet,不来自 prompt。
-4. **visible Goal 与 selected Todo 是两件事。** Goal 能继续,不代表这个 Todo 就该做。
+4. **visible Goal 与 selected Todo 是两件事。**
5. **identity 一律显式传入。** 唯一已注册 lane 可能被自动选中;显式 `--agent-id` 让未注册的身份被拒绝,也让换 lane 成为看得见的选择。
6. **两个 Host 并存需要明确执行归属。** 复核当前 mode 下的 claim、lease 与围栏,不能凭同一 Goal 可读就并发写同一项工作。
diff --git a/docs/book/chapters/07b-when-loopx-is-not-the-answer.md b/docs/book/chapters/07b-when-loopx-is-not-the-answer.md
index cd10e85bc1..96ee1d1eed 100644
--- a/docs/book/chapters/07b-when-loopx-is-not-the-answer.md
+++ b/docs/book/chapters/07b-when-loopx-is-not-the-answer.md
@@ -30,7 +30,7 @@ LoopX 能记录 Goal、acceptance、工作队列、权限和证据,也能通
[状态底座](state-substrate.md)负责工作生命周期事实。LoopX 也有带来源、范围和撤销语义的 Agent 偏好,以及 decision context、reward memory、turn recall 等能力或接入边界。
-这些能力不等于任意聊天都自动进入永久知识库。偏好不是 action authority,召回内容需要检查来源、新鲜度和适用范围;是否可用还取决于当前版本、配置与 provider。
+召回内容需要检查来源、新鲜度和适用范围;是否可用还取决于当前版本、配置与 provider。
**使用判断:** 要保存的是 Todo/回执、明确的用户偏好,还是外部知识材料?先选择已有 owner,再决定保存与召回方式,避免把全部聊天塞进 active state。
diff --git a/docs/book/chapters/08-extension-placement.md b/docs/book/chapters/08-extension-placement.md
index e3c89cc739..be49ecf5e6 100644
--- a/docs/book/chapters/08-extension-placement.md
+++ b/docs/book/chapters/08-extension-placement.md
@@ -187,7 +187,7 @@ Provider 边界、来源 freshness、license 与 credential Gate。
### 2. 现有 Capability 的 Provider
-如果调用者需要的结果已经由一个 Capability 定义,新实现应进入该合同,而不是创建同义 Capability。
+如果调用者需要的结果已经由一个 Capability 定义,新实现应进入该合同。
Provider 可以是:
@@ -331,8 +331,7 @@ generic runner 要求 manifest 和 runtime 的权限都为空。发消息、写
### "多个文件共用代码,所以抽成 Extension"
-共享代码只说明可能存在 helper,不说明需要独立安装和生命周期。抽象应该跟随 change reason,
-而不是文件数量。
+共享代码只说明可能存在 helper,不说明需要独立安装和生命周期。抽象应该跟随 change reason。
## 本书示例的决定
@@ -358,17 +357,17 @@ generic runner 要求 manifest 和 runtime 的权限都为空。发消息、写
如果你要设计的不只是 standalone package,而是 Explore、Domain State、Capability Pack、
multi-agent preset、Provider 或 presentation 的组合,继续阅读
[Control-Plane Course 第 11 讲](/loopx/docs/development/control-plane-course/11-extension-layer/)。
-它解释这些扩展面怎样复用 Kernel,而不是创建第二套 Goal、Todo、Quota 或 Scheduler。
+它解释这些扩展面怎样复用 Kernel。
## 不变式
六句可以自己核对的话。
-1. **一个 capability 的存在理由是它的 caller outcome,不是它的目录名。** 找不到 caller、
+1. **一个 capability 的存在理由是它的 caller outcome。** 找不到 caller、
resolver 和 domain policy,它就不该出现在 catalog 里。
2. **capability 与 extension 是两个维度,一次改动可以只落在其中一个上。** 看到新 package
就直接推断新 capability,是放置错误最常见的形式。
-3. **共享代码并不构成升级成 capability 的理由。** 判据是独立调用合同与生命周期,而非文件数量。
+3. 判据是独立调用合同与生命周期,而非文件数量。
4. **manifest 可发现并不等于合同可调用。** `[[provides]]` 与 `[[implements]]` 只有在真实入口、
resolver 和 validation 就位后才应写入。
5. **Extension 的独立生命周期是用户可见的成本。** 声明它之前先确认这份成本换来了 caller
diff --git a/docs/book/chapters/09-extension-scaffold.md b/docs/book/chapters/09-extension-scaffold.md
index e7a897d8ce..3e42119494 100644
--- a/docs/book/chapters/09-extension-scaffold.md
+++ b/docs/book/chapters/09-extension-scaffold.md
@@ -58,7 +58,7 @@ timeout_seconds = 30
## 用明确的度量定义结果
-`characters` 是 Python Unicode code point 数,`words` 是空白分隔片段数,`lines` 遵循 `str.splitlines()`。所以“你好世界”的 words 是 1,组合字符可能包含多个 code point。这是示例的语义,不是通用自然语言分词。
+`characters` 是 Python Unicode code point 数,`words` 是空白分隔片段数,`lines` 遵循 `str.splitlines()`。所以“你好世界”的 words 是 1,组合字符可能包含多个 code point。这是示例的语义。
示例输入为:
@@ -75,13 +75,13 @@ timeout_seconds = 30
{"characters": 51, "non_whitespace_characters": 44, "words": 8, "lines": 2}
```
-外层同时保留 `ok`、response schema、request schema 与 extension identity。完整输出结构见 `schemas/response.schema.json`;额外的 LoopX managed receipt 不是领域计算结果的一部分。
+外层同时保留 `ok`、response schema、request schema 与 extension identity。完整输出结构见 `schemas/response.schema.json`。
## Decoder 为什么还要自己校验
请求要求 object、精确 schema、非空白 text,并拒绝额外字段。JSON Schema 用于描述 wire shape;decoder 实际执行字段约束,并检查编码、重复键、输入字节上限和 Python 空白语义。
-本例的输入上限是 65,536 字节,text 上限是 32,000 code point。这是教学包自己的限制,不代表 LoopX 全局默认值。
+本例的输入上限是 65,536 字节,text 上限是 32,000 code point。这是教学包自己的限制。
长整数暴露了另一条边界:Python 的 `json.loads` 可能因整数转换限制抛出 `ValueError`,即使数据还没超过字节上限。只捕获 `JSONDecodeError` 会让这个输入越过统一错误结果。
@@ -97,7 +97,7 @@ timeout_seconds = 30
| 5,000 位整数 | 错误 JSON,stderr 无 traceback | Python 3.11+ 整数解析回归 |
| doctor、CLI 输出 | doctor 不处理业务请求,run 输出一个对象 | 真实 provider 子进程入口 |
-源码与测试放在同一个配套目录。测试不调用模型、外部服务或 live Goal,也不证明 managed runtime 的进程回收、权限隔离或升级路径。下一章将这些生命周期步骤单独验证。
+源码与测试放在同一个配套目录。测试不调用模型、外部服务或 live Goal。下一章将这些生命周期步骤单独验证。
## 怎样扩展这个例子
diff --git a/docs/book/chapters/10-extension-lifecycle.md b/docs/book/chapters/10-extension-lifecycle.md
index 3b826a0adf..98bafc9b6e 100644
--- a/docs/book/chapters/10-extension-lifecycle.md
+++ b/docs/book/chapters/10-extension-lifecycle.md
@@ -94,7 +94,7 @@ identity,identity 覆盖 entrypoint 文件内容、所选 Python interpreter
以及 extension 自己声明的 view validator。任何一项变化都会让旧 doctor proof 失效;LoopX 自身的
内置 validator 被刻意排除,因此升级 LoopX 不会连坐所有 extension。
-doctor 的状态是一条阶梯,而不是布尔值:
+Doctor 的状态是一条阶梯:
```text
entrypoint_missing -> identity 无法解析
@@ -198,7 +198,7 @@ loopx extension rollback loopx-text-stats --execute --format json --state-file "
```
rollback 先按 previous revision 记录的 manifest 与入口位置 probe **当前安装的** entrypoint,通过后再
-切换。它不是任意 Git checkout 回退,而是 activation state 中已验证 revision 的生命周期转换。probe
+切换。它是 activation state 中已验证 revision 的生命周期转换。probe
通过不证明旧版本 package 已经装回:若环境里仍是新 package,rollback 后 LoopX 记录的是旧 revision,
实际运行的却是新代码。回滚前后应安装与目标 revision 匹配的 package,再用 `run` 读回实际行为。activation state 保留最近的 validated revision 快照,
数量有限(当前保留 5 个)。
diff --git a/docs/book/chapters/11-engineering-boundaries.md b/docs/book/chapters/11-engineering-boundaries.md
index b5a3b89ecd..ccf9502a25 100644
--- a/docs/book/chapters/11-engineering-boundaries.md
+++ b/docs/book/chapters/11-engineering-boundaries.md
@@ -67,7 +67,7 @@ loopx capability list --format json
loopx extension --help
```
-命令存在不代表完整流程已验证。Host automation、visible Goal 和 Extension activation 需要各自的
+Host automation、visible Goal 和 Extension activation 需要各自的
readback;`doctor --deep` 还会启动并探测发布物携带的 TypeScript Effect runtime。迁移中的
Python facade 成功返回,也不单独证明 TypeScript semantic owner、runtime decoder 和 durable
effect path 都已通过。
@@ -208,5 +208,4 @@ loopx check \
- [ ] internal links 与 public boundary scan 通过;
- [ ] 首页预览已由 owner 审阅。
-完成这些检查后,GitHub Pages workflow 才应从 `main` 发布站点。Pages 是展示面,不是内容或
-LoopX 状态的事实源。
+完成这些检查后,GitHub Pages workflow 才应从 `main` 发布站点。Pages 是展示面。
diff --git a/docs/book/chapters/12-control-plane-course.md b/docs/book/chapters/12-control-plane-course.md
index 34461284e1..f5422d5f40 100644
--- a/docs/book/chapters/12-control-plane-course.md
+++ b/docs/book/chapters/12-control-plane-course.md
@@ -58,7 +58,7 @@ uv sync --extra test
前三组使用临时目录中的真实本地状态或 CLI,第四组使用构造的 quota 输入。它们会写测试状态,也可能启动本地 Effect runtime。不能把 fixture 的 registry、删除或损坏注入步骤替换成 live Goal。缺依赖、收集失败、零项测试或 runtime 不可用,都不等于行为通过。
-源码链接固定到核对过的提交,命令运行你记录的 checkout。先核对版本差异;测试改名时沿原 invariant 找 owner,不把新输出直接抄为期望。这些测试不是模型、真实 Host、远端 provider 或全产品资格验证。
+源码链接固定到核对过的提交,命令运行你记录的 checkout。先核对版本差异;测试改名时沿原 invariant 找 owner,不把新输出直接抄为期望。
### 先读取,再决定是否改变状态 {#read-before-change}
@@ -75,7 +75,7 @@ uv sync --extra test
#### 允许或拒绝的理由 {#state-reason}
-拒绝来自当前源状态或读取失败,不是页面措辞。done/blocked 不能因缓存显示 open 而重新获得准入;authority 不可读也不能证明工作开放。另一方面,显示截断不是拒绝依据:真实存在、当前满足条件的 Todo,可以经精确选择进入本轮。
+拒绝来自当前源状态或读取失败。done/blocked 不能因缓存显示 open 而重新获得准入;authority 不可读也不能证明工作开放。另一方面,显示截断不是拒绝依据:真实存在、当前满足条件的 Todo,可以经精确选择进入本轮。
#### 支持结论的证据 {#state-evidence}
@@ -88,7 +88,7 @@ uv run --extra test pytest -q \
[原测试](https://github.com/loopx-project/loopx/blob/67930ab6af78491f10ca3de4ff74ef7a39954a51/tests/control_plane/test_quota_authority_settlement_journey.py)的第一项断言 `decision=skip`、没有 selected Todo、receipt 为 `not_committed`;第二项断言没有选中项且本轮 receipt 数为零。第三项覆盖 legacy/File/SQLite:精确选择得到 `decision=run`,selected Todo 与 settlement identity 都绑定目标 id,即使它超出展示范围。
-这证明特定路径的来源与选择约束,不证明 provider 已恢复、所有 legacy 路径只读投影,或仅凭 Todo open 就能执行。
+这证明特定路径的来源与选择约束。
#### 下一步入口与停止条件 {#state-next}
@@ -102,11 +102,11 @@ uv run --extra test pytest -q \
#### 事实依据 {#lease-facts}
-分别读取当前 lease 与 original receipt,核对 Goal/Todo、owner、模式、状态、version 与 execution identity。本例仅覆盖 File/SQLite 的 `hard_lease` fixture;同名 Agent 和过去的成功都不是当前执行实例的充分证明。
+分别读取当前 lease 与 original receipt,核对 Goal/Todo、owner、模式、状态、version 与 execution identity。本例仅覆盖 File/SQLite 的 `hard_lease` fixture。
#### 允许或拒绝的理由 {#lease-reason}
-返回历史结果不应复活旧权限。renew 后仍需使用当前 lease 的证明;release 后旧 acquire key 已退役,不能把同一请求变成新的执行。新的 key 也不是绕过拒绝的方法:只有新的工作准入、当前归属和版本条件均满足时,才能获取新 lease。
+返回历史结果不应复活旧权限。renew 后仍需使用当前 lease 的证明;release 后旧 acquire key 已退役,不能把同一请求变成新的执行。只有新的工作准入、当前归属和版本条件均满足时,才能获取新 lease。
#### 支持结论的证据 {#lease-evidence}
@@ -117,7 +117,7 @@ uv run --extra test pytest -q \
[原测试](https://github.com/loopx-project/loopx/blob/67930ab6af78491f10ca3de4ff74ef7a39954a51/tests/control_plane/test_canonical_lease_acquire.py)断言 renew 后 acquire 读回当前 lease,同时保留 original receipt;release 后复用旧 key 得到 `idempotency_key_reuse`。新的合法 acquire 推进版本,完成后 Todo 为 done、lease 为 released;对已完成 Todo 再 acquire 得到 `todo_not_open`。真正完成后 `state.exists()` 为真,并非所有状态文件都被删除。
-这是顺序执行的测试,不证明 soft-claim 的强互斥、TTL 到期后的真实竞争,或外部服务能够拒绝旧执行者的写入。
+这是顺序执行的测试。
#### 下一步入口与停止条件 {#lease-next}
@@ -146,7 +146,7 @@ uv run --extra test pytest -q \
[原测试](https://github.com/loopx-project/loopx/blob/67930ab6af78491f10ca3de4ff74ef7a39954a51/tests/control_plane/test_quota_authority_settlement_journey.py)先从 `spend_required` 到 `settled`,随后仅在 fixture 中移除对应回执。再次写回得到 `spend_receipt_required` 与 `recovery_does_not_spend=true`;执行返回的命令后 `appended=false`,扣减记录仍为一次。最终再次检查达到 `settled` 且没有 `settlement_owed`,下一轮不再卡在这项结算恢复上。
-这些断言证明本例的内部结算恢复,不证明供应商账单为零、不确认其他未知 effect,也不关闭 G1 或接受整个 Goal。测试通过本身不是 live Goal 已恢复的证据。
+这些断言证明本例的内部结算恢复。
#### 下一步入口与停止条件 {#settlement-next}
@@ -166,7 +166,7 @@ uv run --extra test pytest -q \
#### 允许或拒绝的理由 {#monitor-reason}
-是否产生这项 replan obligation,要同时考虑计数、归属和可选工作。这里的五次是具体策略阈值,不是所有等待的定理;current-Agent advancement 可以优先,显式 watch-only 也不受同一重规划触发约束。不产生 obligation 不代表一定有 Host 会醒来,更不自动授权一次写入或交付扣额。
+是否产生这项 replan obligation,要同时考虑计数、归属和可选工作。这里的五次是具体策略阈值;current-Agent advancement 可以优先,显式 watch-only 也不受同一重规划触发约束。
#### 支持结论的证据 {#monitor-evidence}
@@ -178,7 +178,7 @@ uv run --extra test pytest -q \
tests/control_plane/test_settled_replay_construction.py::test_settled_replay_preserves_schedule_without_new_host_effects
```
-[原测试](https://github.com/loopx-project/loopx/blob/67930ab6af78491f10ca3de4ff74ef7a39954a51/tests/control_plane/test_monitor_replan_agent_scope.py)分别断言:只有符合条件的当前 Agent lane 产生 `monitor_no_change_streak`;有当前 advancement 时为 `run` 且没有该 obligation;watch-only 即使 streak 为 50 也不因此触发。它们预置计数器后执行决策,没有交错发送远端 poll,不证明计数写入并发、真实唤醒或 backoff 时间。
+[原测试](https://github.com/loopx-project/loopx/blob/67930ab6af78491f10ca3de4ff74ef7a39954a51/tests/control_plane/test_monitor_replan_agent_scope.py)分别断言:只有符合条件的当前 Agent lane 产生 `monitor_no_change_streak`;有当前 advancement 时为 `run` 且没有该 obligation;watch-only 即使 streak 为 50 也不因此触发。它们预置计数器后执行决策。
这里同时给出一个直接反例:**已结算 Turn 的回放**。该测试在仍有 open advancement successor 时返回
`should_run=false`,但 `scheduler_hint.action` 是 `preserve_current_schedule`、`next_trigger` 是 `fresh_turn_identity`,host action 为 `none` 且不需要 ACK。所以 `false` 的
@@ -197,7 +197,7 @@ uv run --extra test pytest -q \
假设外部写入已经发出,随后响应丢失。现在只有超时和 prepared 意图,缺少能确认结果的读回。**不知道是否发生**与**已经确认没发生**是不同事实;换 operation id 再发一次可能制造第二次效果。
在当前 Turn settlement 的
-[`_resolve_prepared_effect`](https://github.com/loopx-project/loopx/blob/67930ab6af78491f10ca3de4ff74ef7a39954a51/loopx/control_plane/turn_driver/settlement.py)中,没有 resolver、resolver 异常或 unsupported kind 都不能授权执行;有效 committed payload 可供复用,`absent` 才进入未提交分支。这个局部判断仍受外围 journal、身份与恢复条件约束,不是所有外部系统的统一恢复保证。
+[`_resolve_prepared_effect`](https://github.com/loopx-project/loopx/blob/67930ab6af78491f10ca3de4ff74ef7a39954a51/loopx/control_plane/turn_driver/settlement.py)中,没有 resolver、resolver 异常或 unsupported kind 都不能授权执行;有效 committed payload 可供复用,`absent` 才进入未提交分支。这个局部判断仍受外围 journal、身份与恢复条件约束。
| 原身份的读回 | 允许或拒绝的理由 | 下一入口及需要取得的证据 |
| --- | --- | --- |
@@ -213,7 +213,7 @@ uv run --extra test pytest -q \
## 综合练习:一次交付为什么仍未获准? {#integrated-judgment}
-回到[贯穿任务](00-reading-guide.md#running-example)。以下是合成推演,不是新增产品 fixture:T1 在 C1 上验证过且已结算;随后代码变成 C2。M1 仍只有 C1 的绿色 CI 观察,G1 的发布批准尚未完成,T2 有可独立检查的文档工作。
+回到[贯穿任务](00-reading-guide.md#running-example)。以下是合成推演:T1 在 C1 上验证过且已结算;随后代码变成 C2。M1 仍只有 C1 的绿色 CI 观察,G1 的发布批准尚未完成,T2 有可独立检查的文档工作。
| 四问 | 足够具体的答案 |
| --- | --- |
@@ -222,13 +222,13 @@ uv run --extra test pytest -q \
| 哪项证据支持? | 当前 revision 的验证与外部读回、覆盖正确对象/scope 的明确决定,以及当前工作的读回;单独一张绿色截图不足以组合成批准 |
| 下一步找哪个入口? | 经现有验证/Monitor 路径获取 C2 的证据;由维护者通过已有 Gate/Workspace 决定入口处理 G1;独立工作交回当前准入。条件满足后重算 T3,而不是重做已确认的 C1 工作 |
-[权限](work-graph-and-authority.md)、[恢复](04-runtime-boundaries.md)与 [Workspace](workspace-v1.md)分别拥有这些操作说明。Owner 决定不统一由自动 Turn 的 quota 授权;运行某个内部测试也不证明本次真实 CI 或批准已经发生。
+[权限](work-graph-and-authority.md)、[恢复](04-runtime-boundaries.md)与 [Workspace](workspace-v1.md)分别拥有这些操作说明。Owner 决定不统一由自动 Turn 的 quota 授权。
将任务换成“依据两份公开材料完成比较报告”,仍能使用同一判断:材料版本替代 commit,方法与引用检查支持结论,接受人与发布范围需要明确。材料更新后重新检查受影响的分析,不把全部旧讨论变成新证据;报告写完也不自动授权发布。这是概念迁移练习,不宣称另一条产品旅程已经验证。
### 再加一个条件:原 Turn 尚未收口
-若 T1 还欠原身份的等待写回,“T2 独立”并不允许同一 Turn 改绑结算身份。先解释原 Turn 怎样收口,再解释新的准入怎样选择 T2。进阶测试与版本边界见[等待时序](03-one-turn.md#wait-closeout);上面八个测试函数是四组练习选定的范围,不是完整源码的测试清单。
+若 T1 还欠原身份的等待写回,“T2 独立”并不允许同一 Turn 改绑结算身份。先解释原 Turn 怎样收口,再解释新的准入怎样选择 T2。进阶测试与版本边界见[等待时序](03-one-turn.md#wait-closeout);上面八个测试函数是四组练习选定的范围。
再检查协作:A 和 B 各自通过验证,不足以验收组合结果;按[交接到集成](work-graph-and-authority.md#handoff-to-integration)指出采用版本、集成验证、发布决定与最终接受者。
diff --git a/docs/book/chapters/appendix-reference.md b/docs/book/chapters/appendix-reference.md
index 0572497be6..248c1dc4d3 100644
--- a/docs/book/chapters/appendix-reference.md
+++ b/docs/book/chapters/appendix-reference.md
@@ -23,7 +23,7 @@ loopx --registry "$REGISTRY" --runtime-root "$RUNTIME" --format json \
## 从症状找到负责入口 {#diagnostic-routing}
-先找第一处缺少证据的关系,而不是清空整个 Goal。下表是查阅方法,不是新的自动修复状态机。
+先找第一处缺少证据的关系。下表是查阅方法。
| 症状 | 先取得的事实 | 规则与操作入口 | 完成或停止条件 |
| --- | --- | --- | --- |
@@ -57,7 +57,7 @@ Todo 是有身份的工作;frontier 是按当前约束得到的候选;Turn /
## 要求三:明确当前执行者与作用范围 {#requirement-three-one-accountable-actor}
-Agent identity 表达 lane,不证明 Host。Vision 表达适用的 per-Agent 路线。Claim 是归属;lease 在适用 writer/mode 下参与执行证明;Gate 表达具名决定范围;Host 提供实际执行与唤醒条件。这些机制不合成一个全系统唯一行动者,也不自动提供 OS sandbox。详见[工作图](work-graph-and-authority.md)。
+Vision 表达适用的 per-Agent 路线。Claim 是归属;lease 在适用 writer/mode 下参与执行证明;Gate 表达具名决定范围;Host 提供实际执行与唤醒条件。这些机制不合成一个全系统唯一行动者,也不自动提供 OS sandbox。详见[工作图](work-graph-and-authority.md)。
## 要求四:消耗有上限且可外部观察 {#requirement-four-bounded-externally-observable-spend}
@@ -114,7 +114,7 @@ loopx update apply
loopx doctor
```
-先确认安装 owner、目标版本与计划,再授权 apply。普通用户不把 `--ref main` 当成发布版升级默认。成功升级 CLI 不证明所有 Host、Provider 和已有 Goal 状态均已迁移;按实际使用面检查 skills、状态、Host readback 和 enabled Extension readiness。
+先确认安装 owner、目标版本与计划,再授权 apply。普通用户不把 `--ref main` 当成发布版升级默认。按实际使用面检查 skills、状态、Host readback 和 enabled Extension readiness。
需要备份时,先预览再执行:
diff --git a/docs/book/chapters/core-state-machines.md b/docs/book/chapters/core-state-machines.md
index 71cf701880..cd4fc34fc8 100644
--- a/docs/book/chapters/core-state-machines.md
+++ b/docs/book/chapters/core-state-machines.md
@@ -5,13 +5,11 @@
那些机制在文档里分开读时各自成立;真正需要回答的问题在这里:**它们怎样接回同一
条循环?**
-先给结论:**LoopX 由多组状态机协作驱动;但最高一层不是
-“九台机器互相发消息”,而是一条 effectful Agent Loop。** Harness 解释 Agent 或 Host 提出的
+先给结论:**LoopX 由多组状态机协作驱动;最高一层是一条 effectful Agent Loop。** Harness 解释 Agent 或 Host 提出的
effect request,再由 Todo、Gate、Quota、Settlement、Scheduler 等领域状态机判断这一小段流程的
-合法动作。它们通过持久事实、typed contract、guarded transition 和 receipt 衔接,而不是直接
-覆盖彼此的状态。
+合法动作。它们通过持久事实、typed contract、guarded transition 和 receipt 衔接。
-LoopX 不靠一个巨型状态机推进 Goal。它把持久工作、单轮决策、证据结算、调度和界面投影
+它把持久工作、单轮决策、证据结算、调度和界面投影
交给有明确 owner 的协作状态机。本章先建立名词和抽象层级,再解释为什么这样设计,随后看
协作总图,再逐组展开状态机,最后交代这套设计付出的代价。这样你可以先理解主线,再按需深入某一组规则。
@@ -53,27 +51,25 @@ LoopX 不靠一个巨型状态机推进 Goal。它把持久工作、单轮决策
Handoff 等各自维护一张 interpretation table。
所以“LoopX 是多状态机系统”在内层是对的;在外层,更准确的说法是:**一条 Agent Loop 由
-多组有边界的状态机共同解释和约束。** 状态机是 Harness 内部的决策表,不是九个平级微服务,
-也不是九个 Agent。
+多组有边界的状态机共同解释和约束。** 状态机是 Harness 内部的决策表。
## 先认识名词:把“事实、判断、动作、证明”分开
-下面这些词会反复出现。第一次阅读只需记住“它是什么”和“它不是什么”:
+下面这些词会反复出现。第一次阅读只需记住“它是什么”:
先把一轮读成一句白话:**Goal 给出长期边界,frontier 给出当前工作,控制面派生本轮 decision,
Agent / Host 执行 effect,observation 经验证后写回事实,receipt 与 projection 再把下一轮接起来。**
- **目标与工作 — Goal、Todo、frontier、Vision / replan**:Goal 是长期 identity 与边界;Todo
- 是工作项;frontier 是当前可继续的工作边界;Vision / replan 保存路线和改道依据。它们不是一个
- 可整体覆盖的大 Goal 对象,“一条 Todo 完成”也不等于“Goal 完成”。
+ 是工作项;frontier 是当前可继续的工作边界;Vision / replan 保存路线和改道依据。
- **事实与视图 — source / authoritative fact、derived decision、projection**:source 是 owner
可持久写入的事实;decision 是规则算出的本轮判断;projection 是给 Agent、Host 或人看的视图。
- 页面显示的字段不一定可写,projection 也不是第二套事实源。
+ 页面显示的字段不一定可写。
- **动作与证明 — effect request / proposal、observation、transition、evidence、receipt**:proposal
请求动作;observation 报告外部事实;transition 接受合法变化;evidence 支撑判断;receipt 证明
- 有 identity 的提交已经发生。Agent 的请求不等于授权,工具返回也不自动等于完成。
+ 有 identity 的提交已经发生。
- **约束与运行 — Gate、lease、quota、Scheduler / heartbeat、Host / Runtime**:它们分别限定
- 决定范围、临时执行权、本轮计算资格、再次唤醒时间和 effect 执行;不是五种同义的全局锁。
+ 决定范围、临时执行权、本轮计算资格、再次唤醒时间和 effect 执行。
### 先分清三种“状态”
@@ -92,7 +88,7 @@ Todo completion、evidence 和 receipt 的 owner。
## 为什么这样设计,而不是一个大状态机?
-拆分不是为了增加名词,而是因为这些状态天然有不同的变化原因:
+拆分是因为这些状态天然有不同的变化原因:
1. **寿命不同**:Todo 和 evidence 要跨会话保存;quota decision 只对当前 Turn 有效;projection 随时可以重建。
2. **权限不同**:Agent 可以提出 effect;Host 可以执行 effect;只有对应 transition owner 能接受事实变化。
@@ -103,7 +99,7 @@ Todo completion、evidence 和 receipt 的 owner。
如果把它们压进一个 `Goal.status` 或允许 Agent 整体覆盖 `GoalState`,一次写入就可能误删其他
Agent 的进展;一次网络超时也无法判断该重试、回读还是补偿;界面字段还会反向变成事实源。
-协作不等于互相发消息。九组状态机主要通过四种稳定接口连接:
+九组状态机主要通过四种稳定接口连接:
1. **Source facts**:Todo、event、lease、Vision 和 receipt 供 reducer / interpreter 只读。
2. **Typed decision / effect**:`interaction_contract`、selected action 和 scheduler hint 告诉 Agent
@@ -129,7 +125,7 @@ flowchart TD
Facts -.-> Projection["projection Workspace / status"]
```
-这不是“状态机 A 调用状态机 B”的时序图。真正接力的是 source facts、typed decision、effect、
+真正接力的是 source facts、typed decision、effect、
observation 和 receipt;每个状态机只负责自己的 decision table 与合法 transition。
## 从 L0 到 L4:用这些名词回答五个架构问题
@@ -155,13 +151,13 @@ observation 和 receipt;每个状态机只负责自己的 decision table 与
| **Projection** | 把 facts 编译成面向 Agent、Host 或人的视图 | quota/status、Workspace、review packet |
| **Runtime** | 解释本轮 decision 并执行有界 effect | Codex App/CLI、heartbeat、extension provider |
-这些组件不是一条由 Runtime 随意覆盖的 JSON。Runtime 是 effect executor;authoritative state 与
+Runtime 是 effect executor;authoritative state 与
transition owner 才决定事实是否真的改变。
### L2:authoritative state 长什么样?
为了理解,可以先把理想的 Goal 控制面想象成下面的**概念聚合视图**。它描述希望一次读取能够
-回答的问题,不是 LoopX 1.0 已经提供的统一 schema:
+回答的问题:
```yaml
GoalControlSnapshot: # 概念视图;字段是待回答的问题,不是已实现字段名
@@ -209,7 +205,7 @@ acceptance、permissions 和 terminal conditions 目前还没有统一的 typed
### L3:Agent 怎样修改 authoritative state?
-Agent 提交的是 proposal 或 typed effect,不是“我认为新状态应该长这样”的全量覆盖:
+Agent 提交的是 proposal 或 typed effect:
```mermaid
flowchart TD
@@ -223,7 +219,7 @@ flowchart TD
Readback --> Next["派生下一条合法动作"]
```
-这里的“CAS”是并发控制原则,不是假装全仓只有一个整数 `version`:
+这里的“CAS”是并发控制原则:
- Todo completion 会在取得 mutation lock 后比对 admission 相关的字段快照(`status`、`completion_continuation`、`successor_todo_ids`、`validation_command_argv` 等),快照不一致即拒绝,确保针对某份声明的 validation 不能授权另一份已持久化的 Todo;
- shared authority store 以 opaque `expected_provider_revision`(file provider 中对应 generation)做真正的 compare-and-swap;`authority_revision` 和 `lease_epoch` 不能代替它;
@@ -237,8 +233,7 @@ flowchart TD
[`coordination/authority_core.py`](https://github.com/loopx-project/loopx/blob/main/loopx/control_plane/coordination/authority_core.py)
和 [`settlement.py`](https://github.com/loopx-project/loopx/blob/main/loopx/control_plane/turn_driver/settlement.py)。
-所以正确流程是“读 basis -> 提案 -> 验证/guard -> guarded commit -> 事件或 receipt -> 回读”,而不是
-Agent 直接覆盖一份看似完整的状态。
+所以正确流程是“读 basis -> 提案 -> 验证/guard -> guarded commit -> 事件或 receipt -> 回读”。
### L4:Agent 判断错了怎么办?
@@ -255,14 +250,14 @@ Agent 直接覆盖一份看似完整的状态。
这也是为什么 side effect 必须独立建模:模型可以改主意,外部世界却不能靠改一段上下文回滚。
LoopX 通过 validation、版本/identity guard、reconcile、补偿事件和 replan,把错误变成下一条可验证
-transition,而不是让它成为一段失去来路的聊天结论。这里的幂等恢复保证有明确边界:它适用于带
+transition。这里的幂等恢复保证有明确边界:它适用于带
持久 journal、`effect_ref` 和 provider readback resolver 的 settlement step;不能外推成“任意外部工具
调用都会自动去重”。resolver 缺失、报错或返回未知状态时,settlement 会 fail closed。
## 九组状态机怎样组成一条 Loop
现在把刚才那条时间线接回整条循环。维护者级地图把控制面拆成九组协作状态机;“九”是当前
-核心规则的教学地图,不是一个要求所有 extension 都注册九台 runtime service 的协议常量。
+核心规则的教学地图。
本书按读者任务把它们组织为四层:
| 层 | 主要机器 | 回答的问题 |
@@ -293,8 +288,7 @@ flowchart TD
```
图中没有从 projection 直接连回 decision 的写入捷径。界面只能发起受治理动作;真正的 state
-transition 仍由 write API、validation 和 receipt 完成。箭头表示事实和 contract 的依赖关系,
-不是状态机之间的进程消息。
+transition 仍由 write API、validation 和 receipt 完成。箭头表示事实和 contract 的依赖关系。
## 1. 持久工作:Todo、Gate 与 Handoff
@@ -307,8 +301,7 @@ transition 仍由 write API、validation 和 receipt 完成。箭头表示事实
open | done | blocked | deferred
```
-`claimed_by`、`resume_when`、`superseded_by`、`unblocks_todo_id` 和 `no_followup` 是正交字段,
-不是更多 status。它们共同决定下一条合法路径。
+`claimed_by`、`resume_when`、`superseded_by`、`unblocks_todo_id` 和 `no_followup` 是正交字段。它们共同决定下一条合法路径。
```mermaid
stateDiagram-v2
@@ -383,7 +376,7 @@ flowchart LR
| `deferred` | resume condition 尚未满足 | 等待或观察条件 |
这些值是 projection,不应被手工写入。修复 `cleared_without_successor` 的方式是新增合法 successor、
-重开工作或记录 `no_followup`,而不是把显示值改成 `cleared_with_successor`。
+重开工作或记录 `no_followup`。
## 2. 单轮执行:Quota、Interaction Contract 与 Settlement
@@ -402,8 +395,7 @@ flowchart LR
7. paused
```
-这是 reducer 在多个条件同时出现时使用的 precedence,不是 `blocked_health` 会依次流转到 `paused`
-的状态图。每轮都从当前 source facts 重新判定。
+这是 reducer 在多个条件同时出现时使用的 precedence。每轮都从当前 source facts 重新判定。
| Runtime state | 本轮合法动作 | 常见恢复路径 |
| --- | --- | --- |
@@ -415,7 +407,7 @@ flowchart LR
| `throttled` | 不执行交付 | 等待 quota window 或 owner adjustment |
| `paused` | 不执行自动 Turn | 显式 resume;`active/stopped` 由 Goal activation owner 管理 |
-Quota state 不是单独的授权。`interaction_contract` 还会给出 user、agent、CLI channel、workspace
+`interaction_contract` 还会给出 user、agent、CLI channel、workspace
guard、capability gate、selected Todo、execution obligation 和 scheduler hint。Agent 必须执行的是
`must_attempt_work` 是布尔 obligation:为 `true` 时,本轮必须尝试 bounded work 并写回;它本身不选择
动作。需要选择 Todo 时先执行 `selection_command`,否则执行 capability packet 或
@@ -543,7 +535,7 @@ Goal 返回 `canonical_authority_required`,必须先备份并迁移,之后
### Agent Vision / replan:路线改变必须成为 state delta
-Vision 是 per-Agent 的有界可执行路线,不是 scratchpad。正常延续可以提交
+Vision 是 per-Agent 的有界可执行路线。正常延续可以提交
`vision_unchanged_reason`;假设、scope、acceptance 或 route 发生 material change 时,必须提交
bounded Vision patch,并同步 Todo / acceptance delta。
@@ -567,8 +559,7 @@ stateDiagram-v2
### Goal activation 不等于 automation 已启用
-Goal activation 的 typed source 只有 `active` 与 `stopped`。`active` 表示控制面允许继续评估,
-不证明已经安装 Host heartbeat,也不证明当前有 eligible work。完整 onboarding 还要经过:
+Goal activation 的 typed source 只有 `active` 与 `stopped`。`active` 表示控制面允许继续评估。完整 onboarding 还要经过:
```text
project registered
@@ -596,7 +587,7 @@ public/private boundary。
## LoopX 怎样体现“闭环”
-LoopX 的闭环不是“Agent 做了一件事”,也不是 `Todo=done`。更准确的定义是:**一次 effect 的结果
+更准确的定义是:**一次 effect 的结果
经过验证后写回负责该事实的 authoritative source,并且控制面能据此派生出下一条合法动作,或证明
应当停止。**
如果结果只留在聊天、工作区文件、远端系统或 dashboard 文案里,没有 readback、durable writeback
@@ -633,7 +624,7 @@ flowchart TD
1. **结果回来了没有?** 外部 effect 必须有 typed observation 或 readback;“命令退出 0”不能替代
provider、PR、文件 revision 或部署状态的权威回读。
2. **结果落盘了吗?** validation 通过后,evidence、Todo outcome、Vision checkpoint 和 Next Action
- 必须通过 owner write API 持久化;聊天总结不是 writeback。
+ 必须通过 owner write API 持久化。
3. **下一步有归宿吗?** 完成一个 Todo 后必须存在 runnable successor、明确 Gate、带
`resume_when` / `next_due_at` 的等待、repair/replan obligation,或者有证据的 `no_followup`。
4. **Host 知道继续还是停止吗?** scheduler apply 必须有 ACK 或 failure receipt;下一次唤醒重新读取
@@ -677,7 +668,7 @@ coverage-backed `no_followup` 都可以诚实收口;关键是结果可追溯
9. **投影:** Workspace 显示文档已完成、首页仍待决定。界面没有吞掉或扩大 Gate scope。
如果第 5 步失败,流转停在 validation;如果第 6 步失败,不得进入 spend;如果第 8 步 Host 更新
-失败,记录 failure receipt 并有界重试,而不是宣称 cadence 已生效。
+失败,记录 failure receipt 并有界重试。
## 从症状定位 owner
@@ -759,8 +750,8 @@ owner、协议 schema、characterization fixture 和 migration boundary。
**失败三:投影被当成事实源。** dashboard 上改一个 row 让显示正确,source 没变。症状是
UI 与 CLI 长期不一致,而每次刷新都回到旧值。恢复方式是修 source 或 builder,再 readback。
-**失败四:停止的理由并不等于闭环。** Goal `stopped`、quota paused 或 peer coordination blocked
-都可能停止轮询,它们各自是合法停止,但不证明 Goal 闭环。只有 `terminal_no_followup` 表达
+Goal `stopped`、quota paused 或 peer coordination blocked
+都可能停止轮询,它们各自是合法停止。只有 `terminal_no_followup` 表达
"因已验证 Goal closure 而停止"。把这几者混作一谈,会让一个被暂停的 Goal 看起来像已完成。
## 不变式
@@ -774,7 +765,7 @@ UI 与 CLI 长期不一致,而每次刷新都回到旧值。恢复方式是修
处理拒绝结果。
5. **终局是合取。** 完整且闭合的 Todo source、没有未解决 frontier、结构化 `no_followup`
intent,三者同时成立才算闭环。
-6. **教学地图不等于实现规格。** 改规则先确认 typed owner、协议 schema、characterization
+6. 改规则先确认 typed owner、协议 schema、characterization
fixture 和 migration boundary。
这六条回答的是同一个问题:**当机制被拆到九组机器、又只能通过持久事实互相说话时,凭什么
diff --git a/docs/book/chapters/source-change-control-plane-rule.md b/docs/book/chapters/source-change-control-plane-rule.md
index 034040ae4e..d073828a89 100644
--- a/docs/book/chapters/source-change-control-plane-rule.md
+++ b/docs/book/chapters/source-change-control-plane-rule.md
@@ -416,8 +416,7 @@ invariant、画完协议链,通常要几个小时。换到的东西是:这
**边界一:full validation 跑不起全套,这是设计如此。** 本仓库的 [PR 基线](https://github.com/loopx-project/loopx/blob/main/docs/development/testing-and-quality.md) 包含 lint、type、
output budget smoke、`pytest` 分层、`loopx canary premerge --from-git-diff` 和 public/private
scan;真实路径验证(例如 PostgreSQL integration)需要一个一次性隔离实例。开发阶段应当从最
-聚焦的那条命令开始,无需等最宽矩阵。完整公开 smoke fleet 的职责是宽覆盖与健康观察,不是
-每个 PR 的语义设计。
+聚焦的那条命令开始,无需等最宽矩阵。完整公开 smoke fleet 的职责是宽覆盖与健康观察。
**边界二:真实路径不可用时,正确做法是报告证据缺口。** 如果影响 PostgreSQL authority 的
改动拿不到安全的隔离实例,那么"跳过该套件"并不构成通过。此时应暂停交付并说明缺口,不能用
@@ -451,8 +450,7 @@ diff 和描述来发现,这也是为什么下一章把 PR 描述本身当成
**让 renderer 修 policy。** 修改文案不能修复 source 或 authority;反过来,policy 也不应依赖 Markdown 字符串。
-**顺手重构所有相关模块。** 协议链跨多个 bounded context,不等于这个 PR 应当包含每一次可能的
-清理。只改本次 invariant 所要求的完整链条。
+**顺手重构所有相关模块。** 协议链跨多个 bounded context。只改本次 invariant 所要求的完整链条。
**为未来 Host 增加空 adapter。** 没有真实调用方、capability 和 receipt 的 adapter 只增加
维护面,而且它会看起来像一项已经交付的能力。
diff --git a/docs/book/chapters/source-protocol-map.md b/docs/book/chapters/source-protocol-map.md
index be06c6307e..8f7aef9126 100644
--- a/docs/book/chapters/source-protocol-map.md
+++ b/docs/book/chapters/source-protocol-map.md
@@ -12,8 +12,7 @@
- **命中的数量不说明任何事。** 一个权限概念通常在十几个模块里出现——schema、parser、projection、renderer、decision table、test fixture。它们在同一个概念上扮演完全不同的角色。
- **文件会移动,协议责任不会。** 迁移把完整 transaction 的语义搬到了另一侧;按目录名建立的直觉会在下一个版本直接失效。
-- **评审看到的是一份函数清单。** 如果 PR 描述只能说“我改了这三个函数”,reviewer 无法判断被破坏的是哪条不变量,也无法判断在什么条件下应该拒绝它。
-- **测试全绿不代表切片正确。** 针对被改模块的回归测试,恰好会为错误的解释背书。
+- **评审看到的是一份函数清单。** 如果 PR 描述只能说“我改了这三个函数”,reviewer 无法判断被破坏的是哪条不变量,也无法判断在什么条件下应该拒绝它。 针对被改模块的回归测试,恰好会为错误的解释背书。
所以需要一条更慢但更稳定的入口:先说清自己正在改变哪份合同,再去找实现。本章给的是这条入口。
@@ -30,7 +29,7 @@
-> 当前实现与验证
```
-本章给出一张协议优先的源码地图。它不列完整 API,也不要求你记住当前版本的函数名;目标是让你在准备一个 Issue 或 PR 时,先说清自己正在改变哪份合同。
+本章给出一张协议优先的源码地图。目标是让你在准备一个 Issue 或 PR 时,先说清自己正在改变哪份合同。
## 读完之后你应该能
@@ -291,9 +290,9 @@ source facts
| 操作投影 | status/frontstage/projection owner;renderer 只消费 typed read model |
| 文档与验证 | owning protocol 文档、`tests/`、`examples/` 或 public-safe fixture |
-当前 capability 目录采用 package-owned documentation 与 `catalog_entry.py` 注册。贡献前运行 `loopx capability list --format json` 和 `loopx capability show --format json`,确认 capability 是否真实注册、有哪些 entry command、Provider 边界与 durable validation。仅有 目录或 README 不证明能力已经发布。
+当前 capability 目录采用 package-owned documentation 与 `catalog_entry.py` 注册。贡献前运行 `loopx capability list --format json` 和 `loopx capability show --format json`,确认 capability 是否真实注册、有哪些 entry command、Provider 边界与 durable validation。
-`loopx/capabilities//` 中有代码不自动证明它是公开 Capability;需要显式注册和真实 caller contract。`loopx/extensions/` 也不是“所有外部集成”的收纳箱:只有独立 provider lifecycle 才属于这里。私有 helper 留在最近的 owner 中,不因为跨了几个文件就升级为新 Capability 或 Extension。
+`loopx/capabilities//` 中有代码不自动证明它是公开 Capability;需要显式注册和真实 caller contract。`loopx/extensions/` 独立 provider lifecycle 才属于这里。私有 helper 留在最近的 owner 中,不因为跨了几个文件就升级为新 Capability 或 Extension。
## 函数名是搜索锚点,不是课程目录
@@ -381,7 +380,7 @@ acceptance、terminal closure、quota budget 与 monitor cadence 四个可检查
先从 [RFC Index](https://github.com/loopx-project/loopx/blob/main/docs/architecture/rfcs/README.md)
读取正式状态。`Accepted`、`Active research`、`Draft` 与 `Draft integration proposal` 允许的动作
-不同;一份 RFC 或 Discussion 存在,不等于某个实现已经发布,也不自动生成可认领任务。
+不同。
@@ -413,7 +412,7 @@ disposition,并指出 owner、下一产物与复核条件。需要跨方向同
> 重构 status、quota、scheduler 和所有测试。
-缩小切片并不等于减少行数,它要保持一条完整因果链:
+缩小切片要保持一条完整因果链:
```text
source
@@ -459,10 +458,10 @@ grep -rln "required_decision_scopes" loopx/control_plane/todos/ | head
准备进入源码前,确认下面几条能独立成立:
-1. **一条规则的所有者是决定合法转换的模块,不是首次打印相关字样的模块。** 如果无法指出被保护的不变量,这次改动还没有定位到位。
+1. **一条规则的所有者是决定合法转换的模块。** 如果无法指出被保护的不变量,这次改动还没有定位到位。
2. **PR 描述里必须有一条完整的因果链:source、invariant、decision、projection 或 effect、receipt、validation。** 只能列出函数名的切片无法被评审。
3. **文档描述责任归属,代码描述当前行为。** 两者冲突时,按冲突类型选择权威,并让这次 PR 把另一方更新掉。
-4. **`loopx/capabilities//` 下有代码,不证明该 Capability 已经发布。** 注册与真实 caller contract 才是发布判据,用 `loopx capability list --format json` 核对。
+4. 注册与真实 caller contract 才是发布判据,用 `loopx capability list --format json` 核对。
5. **placement 先于实现。** capability id、provider id 与 built-in/extension-delivered 的选择,必须在写第一行代码之前写下理由。
6. **任务来自公开入口。** 公开的 Contributor Task、Issue 和 fixture 是可参与工作的唯一来源,live active state 与 maintainer-local 判断都不算。
diff --git a/docs/book/chapters/source-trace-protocol-chain.md b/docs/book/chapters/source-trace-protocol-chain.md
index bc4b69054f..39fa67963b 100644
--- a/docs/book/chapters/source-trace-protocol-chain.md
+++ b/docs/book/chapters/source-trace-protocol-chain.md
@@ -34,8 +34,7 @@
- **测试覆盖的是你想到的消费者。** 单元测试断言的是被改模块的行为,它不会替你发现另一个模块正在用不同方式读同一个字段。
- **消费关系跨语言、跨层。** 同一个字段可能被 schema 校验、被 parser 归一化、被 projection 重命名、被 renderer 格式化。这四处会分别演进,彼此并不引用。
-- **缺失字段有默认值,而默认值会做出决定。** 缺失被回退成空集合、`None` 或空串时,系统不会报错,它会继续用这个默认值参与判定。这是坏结局最隐蔽的来源。
-- **成功返回值不是证据。** 每一层都成功,合起来仍可能是错的。
+- **缺失字段有默认值,而默认值会做出决定。** 缺失被回退成空集合、`None` 或空串时,系统不会报错,它会继续用这个默认值参与判定。这是坏结局最隐蔽的来源。 每一层都成功,合起来仍可能是错的。
所以调试的问题要换掉。不要问“最终 JSON 为什么不对”,要问“**第一处违反不变量的边界在哪里**”。
@@ -100,7 +99,7 @@ typed Todo / Gate facts
## 第 1 站:Source facts 是否足够表达意图
-先检查 Todo 与 Gate 的 typed facts。下面是**为解释而简化**的形状,不是可直接导入的配置:
+先检查 Todo 与 Gate 的 typed facts。下面是**为解释而简化**的形状:
```json
{
@@ -221,7 +220,7 @@ open work
- `repair-link-checker` 不依赖该 Gate,仍在 frontier;
- Gate 本身继续进入 user channel。
-这不是“安全绕过 Gate”。安全路径没有执行被 Gate 覆盖的 action。
+安全路径没有执行被 Gate 覆盖的 action。
### Ordered policy,而非零散布尔值
@@ -486,7 +485,7 @@ grep -rn "or \[\]\|or ()\|or {}\|\.get(.*, \[\])\|\.get(.*, {})" loopx/control_p
追踪结束后,下面几条应该能独立成立:
1. **每个被改名或改语义的字段,都要能列出全部消费者。** 只改生产者不算完成,缺失字段的回退值算一次消费者。
-2. **链上每一层返回成功,不构成链路正确的证据。** 判断依据是第一处违反不变量的边界,而非最终返回值。
+2. 判断依据是第一处违反不变量的边界,而非最终返回值。
3. **缺失字段的默认值会参与判定。** 因此必须明确写出它是 reject、repair 还是 compatibility fallback。
4. **authority 只有一份 canonical 来源。** 多处可以读同一个字段,只有一处拥有它;读取方被误当成 owner 是跨层变更最常见的解释残留。
5. **判断 authority 时以协议文档为准,判断当前行为时以源码为准。** 两者冲突时按冲突类型选权威,并让同一次改动把另一方更新掉。
diff --git a/docs/book/chapters/source-validation-to-pr.md b/docs/book/chapters/source-validation-to-pr.md
index dc23375458..847dbcfaf1 100644
--- a/docs/book/chapters/source-validation-to-pr.md
+++ b/docs/book/chapters/source-validation-to-pr.md
@@ -34,7 +34,7 @@ public/private scan;完整公开 smoke fleet 是另一回事。更慢的是真
authority 的改动需要一个一次性隔离实例,跑完整套件是分钟到十几分钟量级。每个 PR 都等最宽矩阵,
代价会摊到所有贡献者身上。
-**跑得多不等于覆盖对。** 一百个命令如果都落在同一层,结论仍然只有一层。开头情境中的检查覆盖的是内存中的规则与静态约束,仍需补充受影响后端的证据。
+一百个命令如果都落在同一层,结论仍然只有一层。开头情境中的检查覆盖的是内存中的规则与静态约束,仍需补充受影响后端的证据。
**有些结论需要人工判断。** 自动检查可以提示默认行为变化是否有说明,但披露是否准确、证据是否覆盖真实影响,仍需要 review。
@@ -73,7 +73,7 @@ ambiguous scope -> typed repair
explicit global scope -> global gate
```
-这层最适合证明具体 invariant,但不证明 CLI、projection 与 scheduler 已正确串联。
+这层最适合证明具体 invariant。
### 2. Focused deterministic smoke
@@ -315,7 +315,7 @@ git diff --check
loopx check --scan-path
```
-协议文档若改变 shipped behavior,还应运行对应 contract/smoke;"只改 Markdown"不代表行为风险为零。
+协议文档若改变 shipped behavior,还应运行对应 contract/smoke。
### Python 规则 PR
@@ -574,7 +574,7 @@ ownership 与 receipt。共享同一套新规则的多个 provider 互相一致
记录可重放命令或脚本调用、真实受影响后端、不可变 fixture 指纹、退出状态与归一化观测指纹。
需要说明的是,这条要求在实现上被投影成 review packet 里的一项检查,而 packet 测试只证明要求
-被投影,并不证明 reviewer 真的执行了它,更不证明产品无缺陷。这正是它为什么必须和"默认行为
+被投影。这正是它为什么必须和"默认行为
披露"归为同一类:**这类义务的最后一个执行者是 review,绝非 CI。**
## 两个真实社区贡献案例
@@ -731,7 +731,7 @@ Projection/Docs/fixtures 与 Extension 等贡献面会有不同的最近验证
1. **每一项验证都要对应一个具名风险。** 对应不上的命令属于惯例,构不成本 PR 的证据。
2. **期望值先于实现。** 从当前输出反推的断言只能做 characterization,不能作为 correctness
authority。
-3. **跳过不等于通过。** 拿不到隔离环境时,正确动作是报告证据缺口并暂停交付。
+3. 拿不到隔离环境时,正确动作是报告证据缺口并暂停交付。
4. **默认行为变化有三件必做:重命名 smoke、更新 docs/release note、点名受影响 lane。**
漏掉第一件的测试仍然是绿的,这正是它危险的原因。
5. **merged、released、deployed、observed 是四种状态。** 不能用前一种的证据宣称后一种。
diff --git a/docs/book/chapters/state-substrate.md b/docs/book/chapters/state-substrate.md
index 98011d6222..a51a4282e2 100644
--- a/docs/book/chapters/state-substrate.md
+++ b/docs/book/chapters/state-substrate.md
@@ -1,6 +1,6 @@
# 持久状态与只读投影
-接手一项任务时,最先遇到的问题通常是:哪一份记录代表当前状态?Todo、dashboard、聊天和历史回执可能各自描述不同时间点。能读到旧信息,并不等于能够安全继续。
+接手一项任务时,最先遇到的问题通常是:哪一份记录代表当前状态?Todo、dashboard、聊天和历史回执可能各自描述不同时间点。
## 同一条 Todo,为什么会看到两个状态
@@ -30,9 +30,9 @@ LoopX 在相应 authority 路径上采用最后一种分工。历史 R1 可以
### 精确复用 Goal,不靠文本猜测
-复用依赖 stable `goal_id` 与 registry 路由。多个 Goal 存在时,`start-goal --guided` 提供只读选择,再按精确 id 重跑;相似目标文本不构成静默合并的依据。
+复用依赖 stable `goal_id` 与 registry 路由。多个 Goal 存在时,`start-goal --guided` 提供只读选择,再按精确 id 重跑。
-复用 Goal 和接管 Agent 是不同操作。新会话可以读取原 Goal,但 fresh `agent_id`、已有 lane 的明确复用以及执行 lease 仍有各自的检查。旧聊天或 receipt 不授予新执行者写入权。
+复用 Goal 和接管 Agent 是不同操作。新会话可以读取原 Goal,但 fresh `agent_id`、已有 lane 的明确复用以及执行 lease 仍有各自的检查。
### Todo 存储取决于选定的事实源
@@ -44,7 +44,7 @@ LoopX 在相应 authority 路径上采用最后一种分工。历史 R1 可以
| 已选择 canonical provider 的路径 | 对应 authority 的 Todo snapshot | 兼容工作台或投影 | 以 provider revision 和生命周期读回为准 |
| 旧 Todo `events.jsonl` 实验 | 已退役,不是当前恢复入口 | 不能据旧示例恢复为 authority | 非空旧源需按退役合同处理,不能忽略或清空来过检查 |
-旧 Todo event API、replay、backfill 和 completion 示例已退役,见[退役合同](/loopx/docs/reference/protocols/event-sourced-state-contract-v0/)。这不等于 run history、quota events 或 `rollout_event_log` 也被退役;它们仍有各自的记录职责。
+旧 Todo event API、replay、backfill 和 completion 示例已退役,见[退役合同](/loopx/docs/reference/protocols/event-sourced-state-contract-v0/)。它们仍有各自的记录职责。
## 五类状态表面
@@ -111,7 +111,7 @@ Goal state 保留当前生命周期事实。一次 run 说测试通过,需要
}
```
-这里列的是事实类别与受控写入入口,不是声明所有状态都存进同一种介质。每个字段仍需回到其 owner 和当前 authority 路径解释。
+这里列的是事实类别与受控写入入口。每个字段仍需回到其 owner 和当前 authority 路径解释。
Task graph、Agent management 等投影也声明 `projection_is_writable: false`、`write_api: false`。这些字段描述消费者合同;真正的权限仍由 lifecycle writer 检查,不能仅靠 JSON 中一条声明证明所有入口安全。
@@ -121,11 +121,11 @@ Task graph、Agent management 等投影也声明 `projection_is_writable: false`
[本地写正确性协议](/loopx/docs/reference/protocols/local-state-write-correctness-v0/)用 `prepare -> preview -> apply -> record -> project` 描述目标边界:检查预期 revision,保护相应 lease,提交可读回结果,再更新展示。
-协议仍按 writer 分阶段落实。使用时应核对该命令、authority 模式和 provider 的实际验证,而不是把 draft 中的 hard idempotency、CAS 和 lease enforcement 一次性套到全部 legacy 路径。
+协议仍按 writer 分阶段落实。使用时应核对该命令、authority 模式和 provider 的实际验证。
### 历史基线与当前交付边界
-`v0.5.4` 的 shared-authority 工作引入 provider-neutral TypeScript `AuthorityStore` contract 与候选 provider 验证。后来的本地切换、fencing、projection 和默认入口采用有各自的里程碑;历史版本的能力不应倒推成当前所有路径的上限,也不能把候选资格当成远端服务已交付。
+`v0.5.4` 的 shared-authority 工作引入 provider-neutral TypeScript `AuthorityStore` contract 与候选 provider 验证。后来的本地切换、fencing、projection 和默认入口采用有各自的里程碑。
File/SQLite 的当前本地 authority 路径,应按选定 Goal 的 readback 判断。NoKV/PostgreSQL 等阶段性候选不自动获得 runtime authority;安装 Provider 本身也不改变现有 Goal 的事实源。
diff --git a/docs/book/chapters/work-graph-and-authority.md b/docs/book/chapters/work-graph-and-authority.md
index 047ee2a055..a22ea87aed 100644
--- a/docs/book/chapters/work-graph-and-authority.md
+++ b/docs/book/chapters/work-graph-and-authority.md
@@ -1,6 +1,6 @@
# 工作图、权限与 Peer 协作
-A 可以实现 JSON,B 可以补文档,维护者仍未批准发布。这三件事可以同时成立。工作图的价值是把它们表达成有身份、有依赖和有接受条件的工作,而不是让“有人正在做”成为所有动作的许可。
+A 可以实现 JSON,B 可以补文档,维护者仍未批准发布。这三件事可以同时成立。工作图的价值是把它们表达成有身份、有依赖和有接受条件的工作。
本章先分清工作归属、执行证明与决定范围,再走一次交接和集成。实际写入仍由当前 authority、handoff mode 与对应 writer 校验;本章不新增一个统一授权者。
@@ -26,11 +26,11 @@ A 可以实现 JSON,B 可以补文档,维护者仍未批准发布。这三
| 这个执行实例现在可以提交吗? | 适用模式的 lease、当前 owner/key/version 与 writer fence | 原 acquire 曾成功 |
| 这个具体动作被允许吗? | Goal/repository 权限、Gate scope、能力和工作区要求 | 工具可调用、目录可写或 quota 有余额 |
-Agent identity 是工作 lane,不证明具体 Host,更不证明组织职级。`claimed_by` 表达归属而不是进程活性;lease 的有效性也不能证明模型判断正确。外部服务最终是否拒绝旧执行者,还取决于那个写入端实际执行的约束,不能从本地 lease 推导出全系统围栏。
+Agent identity 是工作 lane。`claimed_by` 表达归属。外部服务最终是否拒绝旧执行者,还取决于那个写入端实际执行的约束,不能从本地 lease 推导出全系统围栏。
## Gate 覆盖动作,不靠数量冻结全局
-G1 限制 T3 的 publication scope。T2 如果确实独立且自己的条件满足,可以继续;G1 仍应在用户通道中可见。独立 fallback 不是绕过 Gate,而是根本没有执行被它覆盖的动作。
+G1 限制 T3 的 publication scope。T2 如果确实独立且自己的条件满足,可以继续;G1 仍应在用户通道中可见。独立 fallback 是根本没有执行被它覆盖的动作。
```text
G1: publication scope 尚未批准
@@ -46,7 +46,7 @@ scope 缺失或矛盾时不能猜成批准,也不能为了省事创造一个
当前 `handoff_mode` 决定适用约束:默认 `legacy` 保留软 claim / hard lease 的兼容路径,`soft_claim` 与 `hard_lease` 有自己的规则。部分 legacy terminal 路径可以出现 `terminal_fence_not_required`。因此,不能把一种模式上的回归测试推广为全部 writer 的强互斥证明。
-对已经提升的 File/SQLite authority,精确读取应来自选定 provider;读取失败不退回旧 lease 文件。来源选择、registration 和当前 Todo 约束与 lease 共同参与判断。`task-lease inspect` 是一次观察,不是跨后续操作持有的锁。
+对已经提升的 File/SQLite authority,精确读取应来自选定 provider;读取失败不退回旧 lease 文件。来源选择、registration 和当前 Todo 约束与 lease 共同参与判断。`task-lease inspect` 是一次观察。
| 生命周期动作 | 在适用合同中表达什么 | 调用者需要保留什么 |
| --- | --- | --- |
@@ -75,7 +75,7 @@ flowchart TD
P --> W["受控执行、验证、提交"]
```
-同名 Agent、重新启动的终端和旧成功截图都不是绕过该过程的方法。`version_mismatch` 应触发当前状态核对;release 后的 `idempotency_key_reuse` 不通过修改历史 key 来“修复”。
+`version_mismatch` 应触发当前状态核对;release 后的 `idempotency_key_reuse` 不通过修改历史 key 来“修复”。
## 从交接到集成:把一次协作走完 {#handoff-to-integration}
@@ -83,17 +83,17 @@ flowchart TD
**第一步,A 返回具体产物。** T1 的回报引用 C1、验证声明和结果,以及尚未满足的 M1/G1。不能只写“JSON 已完成”。
-**第二步,B 确认采用哪份输入。** B 的文档基于 C1 的字段约定;若无法访问该产物,问题是交接输入缺失,而不是需要重新实现 T1。Handoff 使用 bounded refs 和合法读取入口,不把全部私有 transcript 复制到公开 packet。
+**第二步,B 确认采用哪份输入。** B 的文档基于 C1 的字段约定;若无法访问该产物,问题是交接输入缺失。Handoff 使用 bounded refs 和合法读取入口,不把全部私有 transcript 复制到公开 packet。
**第三步,当前归属合法转换。** Lease 转移与 Todo claim 是否同时改变,由所选命令合同决定。不要假设 lease-only transfer 自动改 claim,也不要在要求原子交接的路径上拆成两次手工写。接收方仍须满足 registration、binding、exclusion、scope 和 workspace 条件。对应操作说明以[canonical lease reference](https://github.com/loopx-project/loopx/blob/f49b4a00870604d39fa4318da24d6dd35e72bb6e/docs/reference/canonical-lease-renew.md)中的版本范围为准。
-**第四步,分别验证以后再验证组合。** T1 的代码检查和 T2 的示例检查只证明各自结果;集成者要检查两者在同一个候选版本上是否一致。两个分支都绿,不是组合提交也绿。
+**第四步,分别验证以后再验证组合。** T1 的代码检查和 T2 的示例检查只证明各自结果;集成者要检查两者在同一个候选版本上是否一致。
-**第五步,变化沿依赖传播。** A 将 C1 修正为 C2 时,B 检查字段或行为变化是否影响文档与验证。保留原历史,只更新受影响结论;已经基于 C1 完成的工作不是自动作废,也不是自动适用于 C2。
+**第五步,变化沿依赖传播。** A 将 C1 修正为 C2 时,B 检查字段或行为变化是否影响文档与验证。保留原历史,只更新受影响结论。
**第六步,结果回到接受者。** 由 T3 对当前产物与决定再做判断。消息送达、接收者采用输入、工作被接受、发布被允许、外部交付发生,各有证据;不能用其中一项代替其余全部。
-这个六步过程是教学案例,不是在声明系统会自动完成所有跨 Host、跨设备或跨仓库编排。协作是否成功,必须检查用户所需的关系是否真正闭合。
+这个六步过程是教学案例。协作是否成功,必须检查用户所需的关系是否真正闭合。
## 工作区隔离不等于集成正确 {#parallel-editing}
@@ -110,7 +110,7 @@ flowchart TD
| 两份改动独立验证通过 | 各自产物满足已检查条件 | 组合后行为正确 |
| 集成验证通过 | 当前组合满足相关检查 | 有合并、远端写入或发布权限 |
-该模式是合作式代码编辑协调,不是 OS sandbox。旧 grant 不会因读取或续租自动升级为新模式;需要变更执行意图时,按当前生命周期退役并重新取得证明。安装 provider 或改变目录名不构成提升与授权。
+该模式是合作式代码编辑协调。旧 grant 不会因读取或续租自动升级为新模式;需要变更执行意图时,按当前生命周期退役并重新取得证明。
## 依赖与后继怎样保持可追溯
@@ -118,7 +118,7 @@ flowchart TD
跨仓库依赖需要正确 repository identity。`pr_merged:#123` 可以由 Todo 的 GitHub `task_repository` 解析仓库;显式 `pr_merged:owner/repo#123` 直接指定对象。两者都不能确定仓库时,不按相同编号猜测。
-Successor 表达下一项有身份的工作;supersede 保留旧工作与替代关系(对应生命周期会把 predecessor 记为 done 并标记替代);no-follow-up 说明为什么这一条路线不再需要后继,不能自动等同 Goal 全部验收。`independent_handoff` 与 `same_agent_non_delivery` 表达不同 continuation policy,按实际写回读取而不是从 prose 推断。
+Successor 表达下一项有身份的工作;supersede 保留旧工作与替代关系(对应生命周期会把 predecessor 记为 done 并标记替代);no-follow-up 说明为什么这一条路线不再需要后继,不能自动等同 Goal 全部验收。`independent_handoff` 与 `same_agent_non_delivery` 表达不同 continuation policy,按实际写回读取。
## 用具名证据核对边界
@@ -129,6 +129,6 @@ Successor 表达下一项有身份的工作;supersede 保留旧工作与替代
| 旧 writer 不能绕过已生效来源 | `test_legacy_coordination_writer_fence.py` | 旧模式已被全局删除 |
| runtime root override 不绕过来源围栏 | `test_split_root_todo_writeback_fence.py` | 改一个 CLI 参数就能获得新权限 |
-这些测试属于各自固定输入和 writer 的证据,不是运行中的 Goal 已经健康的证明。练习和断言解释见[lease 检查](12-control-plane-course.md#checkpoint-lease);实际取证入口见[附录](appendix-reference.md#read-before-change)。
+这些测试属于各自固定输入和 writer 的证据。练习和断言解释见[lease 检查](12-control-plane-course.md#checkpoint-lease);实际取证入口见[附录](appendix-reference.md#read-before-change)。
协作的最终标准是:接手者知道接受了什么,当前执行者具有什么资格,组合结果由谁验证,剩余决定由谁负责。范围、证明或输入不清楚时先补齐这一处关系,不重新分派全部任务碰碰运气。
diff --git a/docs/book/chapters/workspace-v1.md b/docs/book/chapters/workspace-v1.md
index ea78827ba8..dc443e37e8 100644
--- a/docs/book/chapters/workspace-v1.md
+++ b/docs/book/chapters/workspace-v1.md
@@ -4,7 +4,7 @@
## 一个界面看起来正常的下午 {#pause-readback}
-以下是合成诊断情境,不是一次已核实的生产事故。
+以下是合成诊断情境。
```text
14:02 operator 打开 Workspace。Manager 总览显示 3 个 Goal,"执行中"车道有两张卡片。
@@ -30,15 +30,13 @@
Workspace 呈现和发起受治理的动作,但 Goal、Todo、Gate、事件、配置和回执仍然由控制面事实源拥有。这带来三个不可避免的后果:
-- **投影会滞后。** 页面上的状态是某个时刻的读模型;在你看到它和它被生成之间,源状态可能已经变化。
-- **HTTP 成功不是写入完成。** 请求被接受和执行完成是两件事,中间可能被 Gate 拦下、被 stale 检查拒绝。
-- **按钮不是独立的授权者。** Goal stop/resume 由 owner 权限与已审核 fingerprint 校验;Todo 操作由生命周期规则校验;自动 Turn 的可运行性再由 quota decision 判断。
+- **投影会滞后。** 页面上的状态是某个时刻的读模型;在你看到它和它被生成之间,源状态可能已经变化。请求被接受和执行完成是两件事,中间可能被 Gate 拦下、被 stale 检查拒绝。 Goal stop/resume 由 owner 权限与已审核 fingerprint 校验;Todo 操作由生命周期规则校验;自动 Turn 的可运行性再由 quota decision 判断。
-所以本章的全部内容可以压成一句:**Workspace 是观察和发起动作的入口,不是一套新的事实源。**
+所以本章的全部内容可以压成一句:**Workspace 是观察和发起动作的入口。**
## 先确认运行时,再看页面
-页面出现不等于控制面健康。先核对版本和诊断,再启动或复用服务;`dashboard --no-open` 不是纯粹的状态查询:
+先核对版本和诊断,再启动或复用服务;`dashboard --no-open` 不是纯粹的状态查询:
```bash
loopx --version
@@ -53,7 +51,7 @@ curl -fsS http://127.0.0.1:8767/chat/ >/dev/null
curl -fsS http://127.0.0.1:8767/status.json
```
-`loopx dashboard` 同时提供打包后的 Workspace、状态投影和 Agent Chat。若相同版本的桌面壳已经启动了服务,它会复用通过 capability fingerprint 验证的进程,而不是启动第二套事实源。**端口只是默认值**;自动化检查应读取命令输出,不要把默认 URL 当成永久合同。
+`loopx dashboard` 同时提供打包后的 Workspace、状态投影和 Agent Chat。若相同版本的桌面壳已经启动了服务,它会复用通过 capability fingerprint 验证的进程。**端口只是默认值**;自动化检查应读取命令输出,不要把默认 URL 当成永久合同。
打开 Workspace 后,先做三项对应检查:
@@ -65,7 +63,7 @@ curl -fsS http://127.0.0.1:8767/status.json
## 把页面读回控制面问题
-Manager 的四条 lane 是 operator 投影,不是四种新的 Todo 状态:
+Manager 的四条 lane 是 operator 投影:
| Lane | 实际含义 |
|---|---|
@@ -94,7 +92,7 @@ Workspace 中的 Goal、Todo、Heartbeat、Monitor 与设置变更遵循同一
typed preview -> human or policy review -> governed apply -> verified receipt -> refreshed projection
```
-**Preview** 冻结规范化参数、影响范围和当前 revision。**Apply** 只能执行仍然匹配该 preview 的动作;状态已经变化时应返回 stale 或 Gate,而不是悄悄套用旧决定。**Receipt 与 readback** 才证明写入完成——按钮点击或 HTTP 成功本身都不够。
+**Preview** 冻结规范化参数、影响范围和当前 revision。**Apply** 只能执行仍然匹配该 preview 的动作;状态已经变化时应返回 stale 或 Gate。**Receipt 与 readback** 才证明写入完成——按钮点击或 HTTP 成功本身都不够。
以暂停 Goal 为例,第一条命令只预览:
@@ -146,7 +144,7 @@ Workspace 的 Lark / 飞书设置可以把一个 Goal 连接到具体 Topic 和
loopx lark-inbox drain --goal-id --agent-id
```
-Disconnect 只移除该 Goal 的 Topic route,不删除 Goal、Session、历史或其他连接。消息到达也不代表 Agent 获得发送、仓库写入或生产权限;这些动作继续通过各自的 Gate 与 Provider readback。
+Disconnect 只移除该 Goal 的 Topic route,不删除 Goal、Session、历史或其他连接。这些动作继续通过各自的 Gate 与 Provider readback。
## 一次生成与持续投递是两条授权链
@@ -158,7 +156,7 @@ loopx periodic-report inspect-profile --preset weekly --format json
回执中的 `active` 与 `generation_allowed` 应同时为 `true`。内置 weekly profile 没有 schedule,也没有 sink,因此**一次生成不会创建周期任务或发送消息**。
-持续报告是另一条授权链:自定义 profile 声明 cadence,Host Automation 负责唤醒;机器或 Goal subscription 的 `enabled: true` 与显式 `route_ref` 构成持续投递授权。暂停 Automation、禁用 profile 或关闭 subscription 会停止对应路径。报告生成成功不等于外部发送成功;Provider、发送身份、route 和消息 readback 仍需分别验证。
+持续报告是另一条授权链:自定义 profile 声明 cadence,Host Automation 负责唤醒;机器或 Goal subscription 的 `enabled: true` 与显式 `route_ref` 构成持续投递授权。暂停 Automation、禁用 profile 或关闭 subscription 会停止对应路径。Provider、发送身份、route 和消息 readback 仍需分别验证。
## 代价与边界
@@ -168,9 +166,9 @@ loopx periodic-report inspect-profile --preset weekly --format json
**代价三:需要理解四层"已启用"的区别。** 把它们压成一个开关会误判能力可用性,而分清它们需要额外的心智负担。
-**边界一:Workspace 不拥有事实。** 界面损坏不能证明控制面仍健康,也不能证明它已经停止。先区分 source、runtime 与 projection;只有源状态和运行条件确认正常时,才把故障限定为显示恢复,而不是通过界面手改状态。它也不构成 Stage 2C authority——shared-authority provider 的资格与提升由独立的 shadow 与 conformance 流程决定,不由某个操作面出现而成立。
+先区分 source、runtime 与 projection;只有源状态和运行条件确认正常时,才把故障限定为显示恢复。shared-authority provider 的资格与提升由独立的 shadow 与 conformance 流程决定。
-**边界二:桌面更新的范围有限。** 更新只能来自固定官方 feed;macOS 使用 updater signature 与 ad-hoc code signing,不应描述为 notarized。回退安装也不承诺逆转未来不兼容的 Goal schema。
+**边界二:桌面更新的范围有限。** 更新只能来自固定官方 feed;macOS 使用 updater signature 与 ad-hoc code signing,不应描述为 notarized。
**边界三:CLI 更新不能修复原生壳缺陷。** 浏览器 / PWA 用户继续使用 CLI update 流程;桌面壳的启动器或 updater 问题需要桌面侧处理。
@@ -188,10 +186,6 @@ loopx periodic-report inspect-profile --preset weekly --format json
## 不变式
-1. **界面是投影,不是事实源。** 每次重要判断前重新读一次源。
-2. **HTTP 成功不证明写入完成。** 只有 receipt 与 readback 能证明。
-3. **点击不构成授权。** Owner 操作由对应 Goal lifecycle 接受,Todo 由其生命周期校验,自动 Turn 由当前 quota contract 准入;页面不重新授予任何一种权限。
+1. 每次重要判断前重新读一次源。
+3. Owner 操作由对应 Goal lifecycle 接受,Todo 由其生命周期校验,自动 Turn 由当前 quota contract 准入;页面不重新授予任何一种权限。
4. **四种"已启用"需要分别证明。** 它们可以互为前提,但不能把一个开关的值当成所有条件均已满足。
-5. **消息到达不扩大权限。** Capture scope 与 ingress mode 都不授予新的写权限。
-
-这五条回答同一个问题:**当界面告诉你"一切正常"时,凭什么相信它?**
diff --git a/docs/book/en/chapters/00-reading-guide.md b/docs/book/en/chapters/00-reading-guide.md
index 073d83c86e..cb28fd9d58 100644
--- a/docs/book/en/chapters/00-reading-guide.md
+++ b/docs/book/en/chapters/00-reading-guide.md
@@ -142,8 +142,7 @@ Operators need not run source tests first; prospective contributors can use
Command categories remain explicit. **Runnable** requires the stated version, inputs, and authorization.
**Based on the official scaffold** follows the existing teaching package without inventing a runtime.
**Simplified for explanation** tables, labels, and data shapes must not be pasted into production
-configuration. Record preview, execution, readback, and test results separately; supplying a command is
-not evidence that it ran successfully.
+configuration.
## Four questions for an accountable explanation {#judgment-standard}
@@ -166,7 +165,7 @@ independent T2 work remains legal. Follow the reasoning in
This is an editorial and learning standard, not a new schema, runtime obligation, or approval gate. When
information is insufficient, name what cannot yet be concluded, the missing evidence, and who can confirm
-it. Do not guess to fill a table. Refusal is not the end goal either: reassess when conditions are repaired,
+it. Do not guess to fill a table. reassess when conditions are repaired,
preserve work that already happened, and find the next legal action.
## How to read the evidence
@@ -178,7 +177,7 @@ preserve work that already happened, and find the next legal action.
| Teaching scenario or advice | Explains a tradeoff; it is not a historical incident or machine-enforced rule |
| Tests and smokes | Establish only exercised inputs and assertions; matching headings/tables, existing paths, and successful builds do not establish semantic correctness |
-During revision, prioritize operational guarantees and bilingual obligation sentences. Narrow unsupported claims and retire obsolete models from current paths. Retaining an old word count is not a reason to keep teaching retired behavior.
+During revision, prioritize operational guarantees and bilingual obligation sentences. Narrow unsupported claims and retire obsolete models from current paths.
## Sources of authority
diff --git a/docs/book/en/chapters/01-from-session-to-loop.md b/docs/book/en/chapters/01-from-session-to-loop.md
index 74f8e32732..4b128e4fc5 100644
--- a/docs/book/en/chapters/01-from-session-to-loop.md
+++ b/docs/book/en/chapters/01-from-session-to-loop.md
@@ -1,7 +1,5 @@
# From one session to long-running work
-An Agent that can edit code, run tests, and explain results inside the current session has not thereby demonstrated that it can reliably own work spanning several days. This chapter explains where that gap comes from, and why closing it needs something that lives outside the session.
-
## An opening that looks fine
Say you want to add `--format json` to an existing CLI:
@@ -58,7 +56,7 @@ It is a poor home for the *only* copy of these facts:
| Which Agent owns the current task | After a restart or handoff, ownership cannot be recovered from memory |
| The current state of the outside world | Yesterday's CI status may already be stale |
-A Host can persist transcripts, but old conversation alone does not establish current authority, acceptance, or recovery state. The test is whether the next executor can recheck those facts without depending on the original session's implicit understanding.
+The test is whether the next executor can recheck those facts without depending on the original session's implicit understanding.
## Execution plane and control plane
@@ -78,7 +76,7 @@ Observation / receipt: return verifiable results
Control plane: accept, reject, or replan
```
-**The control plane does not replace the execution plane.** LoopX does not write code, host Git, or stand in for CI. It lets those systems' results be consumed by a work lifecycle that spans turns — exactly the link missing after 10:17.
+It lets those systems' results be consumed by a work lifecycle that spans turns — exactly the link missing after 10:17.
## Why three long-running workloads share one control plane
@@ -102,7 +100,7 @@ external fact
→ recompute continue | wait | ask | replan | repair | terminal
```
-What is reused is **lifecycle invariants** rather than a generic prompt. Issue-Fix understands `CHANGES_REQUESTED`; Auto ML understands a matched baseline; Auto Research understands holdout. Those domain meanings belong to Capability and Domain State. Who may claim, what is runnable, when to wake again, which evidence permits writeback, and whether the Goal can terminate all come from the same Kernel contract.
+What is reused is **lifecycle invariants**. Issue-Fix understands `CHANGES_REQUESTED`; Auto ML understands a matched baseline; Auto Research understands holdout. Those domain meanings belong to Capability and Domain State. Who may claim, what is runnable, when to wake again, which evidence permits writeback, and whether the Goal can terminate all come from the same Kernel contract.
This boundary also explains why a new domain capability should not clone its own runner, queue, retry, and completion state machine. The domain layer supplies decidable facts and proposals, Providers make external calls, and the Kernel owns cross-domain lifecycle.
@@ -110,7 +108,7 @@ To enter architecture and source entry points through the three showcases, conti
## What minimal externalized state looks like
-For the running example, the minimal state is not the full transcript but a set of facts that answer the recovery questions:
+For the running example, the minimal state is a set of facts that answer the recovery questions:
```yaml
# Simplified for explanation; not a LoopX file format
@@ -129,7 +127,7 @@ next_wake:
when: maintainer decision arrives
```
-The value of these fields: **the next executor does not have to trust the previous Agent's account** and can instead re-derive the next step from the goal, the work queue, Gates, evidence, and a fresh environment. The example is an explanatory model, not LoopX's storage format.
+The value of these fields: **the next executor does not have to trust the previous Agent's account** and can instead re-derive the next step from the goal, the work queue, Gates, evidence, and a fresh environment. The example is an explanatory model.
## Cost and boundary: what this gives up
@@ -141,7 +139,7 @@ Externalized state carries costs. Naming them is what lets you judge when it pay
**Cost three: external facts must be observable.** If CI results, maintainer replies, and external dependency state cannot be read by a program, the control plane can only wait — and waiting needs someone to re-trigger it.
-**Boundary one: this book is about long-running work, not every task.** Work that is closed in scope, finishable in the current context, free of waits on external events, and free of cross-Agent handoff is fine as a plain session — chapter 2 gives the qualification criteria.
+**Boundary one: this book is about long-running work.** Work that is closed in scope, finishable in the current context, free of waits on external events, and free of cross-Agent handoff is fine as a plain session — chapter 2 gives the qualification criteria.
**Boundary two: the control plane does not own domain judgment.** It does not decide whether an issue is worth fixing or whether an experiment's metric is significant; that belongs to Capability.
@@ -149,7 +147,7 @@ Externalized state carries costs. Naming them is what lets you judge when it pay
## Invariants
-1. **Prompt content alone does not prove durable writeback.** Inspect addressable records, identity, and revision rather than whether a window is open.
+1. Inspect addressable records, identity, and revision rather than whether a window is open.
2. **The execution plane and control plane cannot substitute for each other.** The control plane does not write code; the execution plane does not decide whether it is allowed.
3. **What is reused is lifecycle invariants, not a prompt.** That is what lets three different domains share one control plane.
4. **The next executor does not need to trust the previous one's account.** If it does, the state was not externalized far enough.
diff --git a/docs/book/en/chapters/02-session-goal-loopx.md b/docs/book/en/chapters/02-session-goal-loopx.md
index 80630008e3..bdc5b042b1 100644
--- a/docs/book/en/chapters/02-session-goal-loopx.md
+++ b/docs/book/en/chapters/02-session-goal-loopx.md
@@ -44,7 +44,7 @@ the task's completion date does not move.
## Why "big tasks use LoopX, small ones use a session" is not enough
The natural instinct sorts by task size: short work stays in a session, large work escalates to the
-long-running control plane. Neither story fits. The second task was small, three Todos, and a single
+long-running control plane. The second task was small, three Todos, and a single
pending question stalled it for two days.
The decisive variable is this: **when the task stops, what does it need in order to continue?** The
@@ -99,7 +99,7 @@ LoopX coordinates Goals, Agents, and Hosts, but each identity answers a differen
| `agent_id` | Which peer or work lane owns the current responsibility? | Binds claims, Vision, quota, and writeback; new onboarding defaults to a fresh identity only when no registered lane exists or `--new-peer` is explicit |
| `host_surface` / runtime profile | Which product surface executes and wakes this turn? | Binds App heartbeat, a visible Goal, or another Host loop; declare the surface that is actually running |
-Reusing a Goal does not imply that a new session should take over an existing Agent identity. The current
+The current
Goal-start contract keeps those choices explicit:
1. if several registered Goals exist, return a read-only `goal_selection_gate` and rerun with one exact
@@ -113,7 +113,7 @@ Goal-start contract keeps those choices explicit:
`fresh_agent_registration_required` (`register_fresh_agent`), and first onboarding needs no extra
`--new-peer`; a bound thread keeps its bound lane;
5. continue an existing Agent only when the user explicitly selects that exact `agent_id`;
-6. an Agent name or prefix does not prove the Host surface; runtime metadata does.
+6. runtime metadata does.
This lets a session continue the same project without silently impersonating the previous executor.
@@ -225,7 +225,7 @@ claim, lease, successor, and handoff information. Per-Agent Vision stores one pe
direction, acceptance summary, and replan trigger. It is a per-Agent route, not a global product vision.
This separates "the Goal is active" from "who may perform which work now." An agent id labels a LoopX work
-lane; it does not prove which Host is currently executing it. A new session may reuse the Goal history and
+lane. A new session may reuse the Goal history and
frontier, registering a fresh Agent identity when no lane is registered or `--new-peer` is explicit.
Existing claims move only through an explicit takeover or handoff.
@@ -245,7 +245,7 @@ the Host. That second half is exactly what the opening story was missing.
### 3. Evidence and receipt
-"The agent invoked a command" is not proof that a transition happened. LoopX distinguishes:
+LoopX distinguishes:
- proposal: what should happen;
- observation: what was seen;
diff --git a/docs/book/en/chapters/02b-long-horizon-requirements.md b/docs/book/en/chapters/02b-long-horizon-requirements.md
index 42167685f7..89d50518d1 100644
--- a/docs/book/en/chapters/02b-long-horizon-requirements.md
+++ b/docs/book/en/chapters/02b-long-horizon-requirements.md
@@ -11,17 +11,17 @@ A repair can span code edits, tests, CI waiting, review, handoff and delivery. E
| How do executors collaborate? | Assignment, scope and current execution proof | Claims, leases, fences and commit checks |
| How does no-change work consume less? | Budget, wait target, observations and actual execution conditions | Quota, Monitors, scheduler/backoff and Host |
-Long-running work needs neither an immortal process nor a delivery on every wake. Legitimate waiting and honest stopping also need representation.
+Legitimate waiting and honest stopping also need representation.
## Demand one: state outlives the current context
-A recipient needs the exact PR, commit, validated behavior and outstanding decisions, not merely “I fixed it.” Chat may persist and explain history, but persistence alone supplies neither structure, freshness nor current permission.
+A recipient needs the exact PR, commit, validated behavior and outstanding decisions, not merely “I fixed it.”
Consequential facts need an addressable source, applicable revision and read entrypoint. Maintaining records has a cost; the benefit is reassessing conditions after session change rather than filling gaps from memory. In the [state chapter](state-substrate.md), distinguish source from display under the selected mode.
## Demand two: retain known facts and uncertainty
-An external operation can succeed while its local response is lost. A missing local record proves neither remote absence nor completion.
+An external operation can succeed while its local response is lost.
Governed Turns represent confirmed progress through phases and receipts and read unresolved effects under original identity. Legal prefixes constrain records, not the crash window between external commit and checkpoint. The original owner resolves uncertainty; a new key must not bypass it. Only supported outcomes and current permission allow reuse or outstanding execution.
@@ -31,7 +31,7 @@ Historical recovery and admission for a new execution answer different questions
Agents can handle different work or both believe the same item belongs to them. Claims express responsibility; applicable leases/fences constrain the current instance. Neither replaces Goal boundaries, Gate scope, capability or workspace conditions.
-Default legacy, soft-claim and hard-lease paths have distinct enforcement boundaries. One mode does not establish universal exclusion, and multiple peers do not imply one executor for the entire Goal. Tie takeover and parallelism to a concrete writer and current inputs; see [authority layers](work-graph-and-authority.md#authority-layers).
+Default legacy, soft-claim and hard-lease paths have distinct enforcement boundaries. Tie takeover and parallelism to a concrete writer and current inputs; see [authority layers](work-graph-and-authority.md#authority-layers).
## Demand four: budget and observation constrain repetition
diff --git a/docs/book/en/chapters/03-one-turn.md b/docs/book/en/chapters/03-one-turn.md
index 7ef28ebffc..188571dfbb 100644
--- a/docs/book/en/chapters/03-one-turn.md
+++ b/docs/book/en/chapters/03-one-turn.md
@@ -52,7 +52,7 @@ Evidence becomes an accepted work fact through the relevant lifecycle entrypoint
| Evidence | Materials supporting a conclusion | A record that a transition was accepted |
| Receipt | Acceptance of a bound operation under its inputs and conditions | Current execution rights or an unchanging external world |
-For example, a `git push` timeout is a call outcome. A remote-ref readback may establish that a commit is present, but not necessarily which invocation caused it, and it does not automatically create a LoopX delivery receipt. Resolve the original operation before its writeback; timeout is not proof of absence.
+For example, a `git push` timeout is a call outcome. A remote-ref readback may establish that a commit is present, but not necessarily which invocation caused it, and it does not automatically create a LoopX delivery receipt. Resolve the original operation before its writeback.
## Scale one: execute, validate and commit
@@ -60,7 +60,7 @@ Normal delivery has five useful stages: `Decide → Act → Validate → Write b
**Decide** reads the current `interaction_contract` and selected work. An old prompt, card or recommendation does not override current selection.
-**Act** produces a coherent segment with explicit inputs and boundaries. Bounded does not mean one line: an independently verifiable feature slice is more useful than fragments that cannot be accepted.
+**Act** produces a coherent segment with explicit inputs and boundaries. an independently verifiable feature slice is more useful than fragments that cannot be accepted.
**Validate** checks postconditions. Code needs behavioral validation, documentation needs command and explanation checks, external effects need appropriate readback, and blockers need inspectable missing conditions. An exit code matters only when the validator actually checked the intended postcondition.
@@ -112,7 +112,7 @@ After obtaining `settlement_owed.command` from a trusted current entrypoint, ver
“Independent work may continue” has a timing boundary. A Turn already bound to T1 does not switch its settlement identity to T2 merely because T1 discovers a dependency.
-This is an **advanced source comparison**, grounded in the [original-Turn wait recovery test](https://github.com/loopx-project/loopx/blob/f49b4a00870604d39fa4318da24d6dd35e72bb6e/tests/test_quota_bound_wait_recovery.py) at main `f49b4a00…`. The current source includes that implementation. The pinned link supports verification; it does not establish shipped `v1.2.3` behavior or make the example executable on an older checkout.
+This is an **advanced source comparison**, grounded in the [original-Turn wait recovery test](https://github.com/loopx-project/loopx/blob/f49b4a00870604d39fa4318da24d6dd35e72bb6e/tests/test_quota_bound_wait_recovery.py) at main `f49b4a00…`. The current source includes that implementation. The pinned link supports verification.
```text
Original Turn binds T1 and records a monitor_changed / todo_done dependency
@@ -162,7 +162,7 @@ An owner stopping a Goal in the Workspace uses its lifecycle authority; automati
Migrated transactions have TypeScript owners; Python handles adapters or explicit external effects. Known slices include Turn settlement, Todo completion, Host Todo settlement, spend/void/monitor-poll commit, the full local task-lease lifecycle, Vision refresh and receipt-bound scheduler follow-up.
-`v0.5.4` still ships `turn plan` / `turn run-once`: this is historical migration context, not a replacement label for the current release or evidence that “Python has been removed.” The [TypeScript Control-Plane Migration RFC](/loopx/docs/architecture/rfcs/typescript-control-plane-migration-v0/) explains transaction-payoff and ownership boundaries. Diagnose disagreement from the current contract and caller path, not from a blanket preference for one language.
+`v0.5.4` still ships `turn plan` / `turn run-once`: this is historical migration context. The [TypeScript Control-Plane Migration RFC](/loopx/docs/architecture/rfcs/typescript-control-plane-migration-v0/) explains transaction-payoff and ownership boundaries. Diagnose disagreement from the current contract and caller path.
## Readback and the chapter's exit condition
diff --git a/docs/book/en/chapters/04-runtime-boundaries.md b/docs/book/en/chapters/04-runtime-boundaries.md
index 1b891b16c2..bda072833a 100644
--- a/docs/book/en/chapters/04-runtime-boundaries.md
+++ b/docs/book/en/chapters/04-runtime-boundaries.md
@@ -82,17 +82,17 @@ Dreaming proposes directions or hypotheses; it does not acquire execution author
## Material evidence delta: activity is not progress
-Imagine a teaching case in which a day produces notes, unrelated tests and directory reorganization, but reduces none of the acceptance gaps. The artifacts may exist; that alone does not establish convergence. This is not a claim that current policy unconditionally permits infinite repetition.
+Imagine a teaching case in which a day produces notes, unrelated tests and directory reorganization, but reduces none of the acceptance gaps. The artifacts may exist.
Material evidence delta concerns new evidence or state that changes the next judgment, not counts of turns, files or characters. Negative results can matter: rejecting a hypothesis, confirming a blocker or narrowing an unknown can change the route.
-Delivery Batch Scale describes change scope; Delivery Outcome describes its relation to the objective. `multi_surface` or `implementation` does not automatically complete a Goal. Interpret `surface_only`, `outcome_gap`, `outcome_progress` and `primary_goal_outcome` under their contract; an attractive label is not evidence.
+Delivery Batch Scale describes change scope; Delivery Outcome describes its relation to the objective. `multi_surface` or `implementation` does not automatically complete a Goal. Interpret `surface_only`, `outcome_gap`, `outcome_progress` and `primary_goal_outcome` under their contract.
### Vision checkpoints and baselines
Vision is a per-Agent execution route, not a scratchpad. Applicable material refresh must account for a patched route, supported unchanged result, retirement/supersession, or why the role does not require Vision.
-“Unchanged” needs a comparable baseline. Establish the route when none exists rather than describing never-checked as unchanged. For gaps such as `vision_checkpoint_missing`, return to the checkpoint owner and supply the actual relationship, not more aspirational prose. Current owners still determine precedence among replanning and repair; this explanation is not a global rule table for all Hosts.
+“Unchanged” needs a comparable baseline. Establish the route when none exists rather than describing never-checked as unchanged. For gaps such as `vision_checkpoint_missing`, return to the checkpoint owner and supply the actual relationship, not more aspirational prose. Current owners still determine precedence among replanning and repair.
### Six convergence invariants
@@ -105,7 +105,7 @@ These questions check completeness; they add no public fields or automatic accep
5. **Liveness:** does unfinished work have an action, executable observation, decision, repair or explicit stopping responsibility?
6. **Terminal state:** were successors, waits, receipts and acceptance gaps handled under the applicable contract, rather than merely finding an empty list?
-Safety avoids incorrect progress; liveness avoids getting stranded without a next entrypoint. Neither guarantees arbitrary objectives will succeed. See [long-horizon convergence](/loopx/docs/development/control-plane-course/topic-long-horizon-convergence/) and [evidence and repair](/loopx/docs/development/control-plane-course/08-evidence-refresh-and-self-repair/).
+Safety avoids incorrect progress; liveness avoids getting stranded without a next entrypoint. See [long-horizon convergence](/loopx/docs/development/control-plane-course/topic-long-horizon-convergence/) and [evidence and repair](/loopx/docs/development/control-plane-course/08-evidence-refresh-and-self-repair/).
## Which surface should be repaired when two disagree? {#projection-repair}
@@ -124,7 +124,7 @@ Legacy Markdown can still be source; a Todo under a selected canonical provider
## Stop, closure and compensation
-An owner-stopped Goal, paused quota or exited Host does not prove completion. `terminal_no_followup` needs its frontier/acceptance conditions. Zero visible Todos is insufficient: output may be truncated, or Monitors, Gates, successors, handoff, replanning and result-return responsibilities may remain.
+`terminal_no_followup` needs its frontier/acceptance conditions. Zero visible Todos is insufficient: output may be truncated, or Monitors, Gates, successors, handoff, replanning and result-return responsibilities may remain.
When requirements are satisfied, record the basis through the existing terminal entrypoint. Keep a successor for unfinished work or observation/blocker for unknown results. Verified negative results and coverage-backed no-follow-up can honestly end a route without inventing success.
@@ -150,7 +150,7 @@ A writeback may mark the vision unchanged only when all of the following hold:
vision as the baseline automatically, so no separate revision is passed.
If the baseline is missing but the agent still claims unchanged, quota will produce a
-`vision_checkpoint_missing` gap. This is not a punishment, but a guard against the agent accumulating
+`vision_checkpoint_missing` gap. a guard against the agent accumulating
wrong assumptions on a never-checked state. For the full failure replay, see
[Control-Plane Course Lesson 8](/loopx/docs/development/control-plane-course/08-evidence-refresh-and-self-repair/).
diff --git a/docs/book/en/chapters/04b-budget-and-admission.md b/docs/book/en/chapters/04b-budget-and-admission.md
index eb369c3a2d..f852135c3a 100644
--- a/docs/book/en/chapters/04b-budget-and-admission.md
+++ b/docs/book/en/chapters/04b-budget-and-admission.md
@@ -1,6 +1,6 @@
# Bounded spending and external observation
-After T1 finishes, M1 may still await CI for C1 and G1 may still await a publication decision. Remaining budget does not justify repeatedly invoking a model; no message does not prove the external world is unchanged. Separate whether to act, when to look again, who observes, and when to reconsider the route.
+After T1 finishes, M1 may still await CI for C1 and G1 may still await a publication decision. Remaining budget does not justify repeatedly invoking a model. Separate whether to act, when to look again, who observes, and when to reconsider the route.
## Separate five responsibilities {#observation-owners}
@@ -25,7 +25,7 @@ The following is a **hypothetical faulty policy**, not a claim that current impl
| 11:00 | M1 | M1's second unchanged observation | Switch again and start counting again |
| 11:30 | M1 and M2 are each due | Update each observation independently | Depends on processing order rather than actual stagnation |
-The problem is not a high threshold; it is conflating different targets. Preserve each Monitor's identity and count instead of repeatedly lowering the threshold. Conversely, without a usable Host executing due observations, correct counters remain static records: that is a liveness gap, not no-change evidence.
+Conflating different targets. Preserve each Monitor's identity and count instead of repeatedly lowering the threshold. Conversely, without a usable Host executing due observations, correct counters remain static records: that is a liveness gap, not no-change evidence.
## Choose an observation frequency while waiting for CI {#running-wait}
@@ -61,7 +61,7 @@ When T1 discovers a real dependency, record a specific target such as `monitor_c
Independent T2 in the work graph does not let a Turn already bound to T1 rebind itself. Complete the original Turn's required blocked writeback and closeout, then let later admission select new work. **Turn closeout, Todo waiting and next-turn selection are three different facts.**
-The [Turn chapter's wait sequence](03-one-turn.md#wait-closeout) explains this path with an explicit test from main `f49b4a00…`, labeled separately from older release promises. It checks no duplicate debit, no forced Monitor poll, and retained waiting/validation declarations. It is not a universal scheduling order for all Hosts.
+The [Turn chapter's wait sequence](03-one-turn.md#wait-closeout) explains this path with an explicit test from main `f49b4a00…`, labeled separately from older release promises. It checks no duplicate debit, no forced Monitor poll, and retained waiting/validation declarations.
## Cadence backoff versus route replanning
diff --git a/docs/book/en/chapters/05-connect-existing-project.md b/docs/book/en/chapters/05-connect-existing-project.md
index 7fe85e155d..04cf47b0eb 100644
--- a/docs/book/en/chapters/05-connect-existing-project.md
+++ b/docs/book/en/chapters/05-connect-existing-project.md
@@ -18,7 +18,7 @@ Use your actual project and current packet for commands; T1, M1, and C1 are not
## Three different completion points {#three-completions}
-Installing, connecting, and delivering are not the same accomplishment. Installation asks whether the
+Installation asks whether the
CLI and required runtime are usable. Connection asks whether work identity, state location, and execution
route are explicit. Delivery asks whether the actual artifact meets its current acceptance conditions.
A connected project may have no executing Turn; a successful Turn may still leave external checks or
@@ -151,8 +151,7 @@ git ls-files .loopx .loopx/goals .local
```
Repository root, current branch, and existing changes are separate facts. Do not reset or delete valuable
-changes. In a linked worktree, identify the tree where delivery will actually happen. A clean status in
-one directory does not establish that no work happened in another.
+changes. In a linked worktree, identify the tree where delivery will actually happen.
A project may already contain `.loopx/registry.json` or `.loopx/goals/`. Identify existing Goals, in-flight
work, and state locations first. Do not copy another project's registry or overwrite useful state to
@@ -197,8 +196,7 @@ git check-ignore -v .loopx/goals/example/ACTIVE_GOAL_STATE.md
mean the path is ignored. Tracked files are not governed by ignore rules by default. `--no-index`
diagnoses rules without considering the index; it neither forces exclusion nor specifically handles
nonexistent files. By default, `ls-files` lists paths in the current index. Output means tracked or staged
-content, **not necessarily a pushed commit**. No output does not prove that past commits or a remote have
-never contained sensitive material. See [Git check-ignore](https://git-scm.com/docs/git-check-ignore)
+content, **not necessarily a pushed commit**. See [Git check-ignore](https://git-scm.com/docs/git-check-ignore)
and [Git ls-files](https://git-scm.com/docs/git-ls-files).
When local state is tracked unexpectedly, inspect its contents, staging, and history before an authorized
@@ -233,8 +231,7 @@ to the implementation and regression exercises later in the book. For an existin
installation, use the [appendix's upgrade guidance](appendix-reference.md) to identify the installation
owner instead of layering another installation over an unexplained one.
-`doctor` answers more about dependencies, installation, and integration than `command -v loopx`, but it
-is not proof that every Host journey has been qualified. For the actual Effect runtime and journal
+`doctor` answers more about dependencies, installation, and integration than `command -v loopx`. For the actual Effect runtime and journal
checkpoint path, use the deeper probe when needed:
```bash
@@ -279,8 +276,7 @@ loopx start-goal --guided --project . \
--goal-text "Add compatible JSON output while preserving default text; deliver after validation and documentation, without automatic publication"
```
-The response is a guided transaction packet. A successful preview does not establish that Todos were
-written, an Agent was registered, or a Host started. Read the selection it currently requires and
+The response is a guided transaction packet. Read the selection it currently requires and
continue with its exact commands; do not revive an obsolete instruction from an earlier conversation.
When several Goals exist, select an exact `goal_id` from `goal_selection_gate` choices. Similar objective
@@ -325,7 +321,7 @@ when the Host is unknown rather than substituting a familiar name for observatio
readback belong to the [Codex App](06-codex-app.md) and [Codex CLI](07-codex-cli.md) chapters; other
adapters are indexed in the [Runtime Connector Catalog](/loopx/docs/integrations/runtime-connector-catalog/).
Type registration, launchability here, autonomous continuation inside a process, and waking after that
-process exits are distinct conditions. An accepted argument does not prove them all.
+process exits are distinct conditions.
## 4. Accept the connection: which next step is supported now? {#connection-acceptance}
@@ -377,7 +373,7 @@ objective content, and credentials before sharing it publicly.
## 5. From connection to the first delivery {#first-delivery}
Return here after the Host chapter. The goal is an independently verifiable work segment, not a screen
-that says running. This walkthrough is not an end-to-end test of a real Host; accept actual work using
+that says running. accept actual work using
evidence from your own run.
### Scene one: A owns T1, not the entire publication workflow
@@ -415,15 +411,14 @@ Internal quota accounting is also not the model supplier's actual bill.
Local validation cannot replace M1's observation of remote C1. Registered waiting should identify its
target, applicable revision, next observation, and termination or ongoing-watch policy, with an actually
available execution surface. Supported boundedness choices include expiry, a resume condition, or
-explicit watch-only; one field is not the only valid choice for every Monitor.
+explicit watch-only.
When G1 has not approved publication, T3 obtains no authority from green CI or T1 settlement. T2 may
continue when it is still provably independent and its own constraints hold. A user decision can be
required while an Agent continues different work. See [observation and scheduling](04b-budget-and-admission.md)
and [the work graph](work-graph-and-authority.md).
-An unchanged observation must not impersonate delivery; it can still incur compute and network cost.
-No notification is not evidence that the external source stayed unchanged. When the Host has exited
+An unchanged observation must not impersonate delivery; it can still incur compute and network cost. When the Host has exited
with no available waking mechanism, report the operational gap rather than calling quietness healthy waiting.
### Scene four: changed conditions call for changed judgments
@@ -456,8 +451,7 @@ For example, as a local report rather than another persisted format:
> publication decision is still outstanding, so return the artifact for review without publishing.
> G1's decision entrypoint comes next; once accepted and still applicable, reassess T3.
-Even without saying everything is complete, this report supports a handoff. “Tests green, task done”
-provides neither the scope of what was proved nor the responsibilities still outstanding.
+Even without saying everything is complete, this report supports a handoff.
## 6. Delegate onboarding to an Agent without delegating guesses about authority {#delegate-onboarding}
diff --git a/docs/book/en/chapters/06-codex-app.md b/docs/book/en/chapters/06-codex-app.md
index f9a888e531..18b484f0df 100644
--- a/docs/book/en/chapters/06-codex-app.md
+++ b/docs/book/en/chapters/06-codex-app.md
@@ -56,8 +56,7 @@ Agent Turn no delivery
validate -> writeback -> optional spend
```
-The right branch is a legal outcome, and it is the common one. It means no work was due for **this** turn; it
-does not mean the Goal frontier is closed. A settled turn's replay returns `should_run=false` while preserving
+The right branch is a legal outcome, and it is the common one. It means no work was due for **this** turn. A settled turn's replay returns `should_run=false` while preserving
the current cadence and deferring evaluation to a fresh Turn identity. Landing there often is therefore not
evidence that the cadence should slow down. Apply the four steps below only when the current `scheduler_hint`
proposes a change (`apply_needed=true`).
@@ -106,8 +105,7 @@ before the Todos exist, and each wake receives a Goal with no frontier yet. Writ
very first wake already has a defined candidate.
You do not have to run every internal command yourself, but you should be able to see these transitions in
-the Agent's report. A natural-language plan is not proof that project state exists, and a guided packet is
-not proof that a heartbeat has been installed. Each needs its own readback.
+the Agent's report. Each needs its own readback.
## Every wake still passes the quota Gate
@@ -194,14 +192,13 @@ something that settles as fast as assigning a local variable.
both exit successfully. Telling them apart requires the writeback and spend history, not the heartbeat log.
**Boundary one: a heartbeat does not create a frontier.** A Goal with no Todos will not produce a next step
-because it was woken more often. The App guarantees someone looks; it does not guarantee there is anything
-to do. With no runnable candidate, enter wait or monitor and let the cadence slow.
+because it was woken more often. With no runnable candidate, enter wait or monitor and let the cadence slow.
-**Boundary two: the automation is not a second control plane.** Do not copy the quota state machine into
+Do not copy the quota state machine into
the automation prompt, and do not let it resolve runnable Todos on its own. The stable prompt carries
protocol; the judgment belongs to the packet read on each wake.
-**Boundary three: switching Hosts requires ownership checks.** App and CLI may read one Goal. Check the old instance, current claims/leases, and writer-fence mode. Use lifecycle handoff where required; a newly started Host does not authorize concurrent work on the same item.
+**Boundary three: switching Hosts requires ownership checks.** App and CLI may read one Goal. Check the old instance, current claims/leases, and writer-fence mode. Use lifecycle handoff where required.
## When to choose App, and when to choose CLI
@@ -264,7 +261,7 @@ repeat reminders so that a wait does not become a high-frequency notification.
this turn's receipt is grounds to slow the cadence. Slowing happens when the current `scheduler_hint`
proposes it (`apply_needed=true`), through the four steps below.
4. **A cadence change needs all four steps**: proposal, host apply, host readback, ACK.
-5. **A local ACK ledger does not prove Host state.** Only a Host readback that matches the target closes the
+5. Only a Host readback that matches the target closes the
loop; a mismatch is repaired as `drift_detected`.
6. **Switching Hosts needs explicit handoff.** Shared Goal reads do not replace current authority, claim/lease, and fence checks.
diff --git a/docs/book/en/chapters/07-codex-cli.md b/docs/book/en/chapters/07-codex-cli.md
index 0a512b3e6e..6f344d8e31 100644
--- a/docs/book/en/chapters/07-codex-cli.md
+++ b/docs/book/en/chapters/07-codex-cli.md
@@ -4,7 +4,7 @@ A visible TUI can also sustain progress. LoopX generates a stable task body for
## Why an active Goal differs from a background wake
-Suppose a fix is unfinished and you terminate its Codex process. No further work occurs before you restart it. The execution environment has exited; this does not mean a live native Goal needs a user message for every turn.
+Suppose a fix is unfinished and you terminate its Codex process. No further work occurs before you restart it. The execution environment has exited.
| Host state | Behavior on this path | What the user needs to establish |
| --- | --- | --- |
@@ -116,7 +116,7 @@ another Host or another lane, the work's ownership was silently rewritten. With
unregistered id is rejected, and a registered id that differs from the thread binding is treated as a
deliberate override, so pass one only when you mean to switch lanes.
-Agent identity labels the LoopX lane. It does not prove that the work runs in Codex CLI. Use
+Agent identity labels the LoopX lane. Use
`host_surface`, runtime profile, or run metadata to identify the Host.
A proper handoff is:
@@ -132,7 +132,7 @@ A proper handoff is:
**Continuation depends on an executable Host state.** An active native Goal can progress autonomously; process exit and blocked state have separate boundaries. Automatic wakes across those boundaries require the corresponding scheduling integration and readback.
-**Visibility does not replace validation.** A TUI shows activity; success still needs validation, writeback, and settlement. Whether someone watches the screen does not change those conditions.
+A TUI shows activity; success still needs validation, writeback, and settlement. Whether someone watches the screen does not change those conditions.
**Handoff requires current authority checks.** App and CLI can read the same Goal. Check claim, lease, worktree, and applicable writer-fence mode when changing executors to avoid concurrent submission of the same effectful work.
@@ -144,7 +144,7 @@ A proper handoff is:
| Check again on cadence after a long wait | App heartbeat or a qualified scheduler integration | Actual automation, cadence, and ACK/readback |
| Continue after process exit | Resume the existing Goal or use a path supporting that boundary | An old prompt is not a new execution environment |
-Select the wake mechanism you need. Visible execution does not mean manually triggering every turn. Both paths must read the current LoopX decision.
+Select the wake mechanism you need. Both paths must read the current LoopX decision.
## Recovery paths
diff --git a/docs/book/en/chapters/07b-when-loopx-is-not-the-answer.md b/docs/book/en/chapters/07b-when-loopx-is-not-the-answer.md
index 1f44a00956..3e5ed55b1a 100644
--- a/docs/book/en/chapters/07b-when-loopx-is-not-the-answer.md
+++ b/docs/book/en/chapters/07b-when-loopx-is-not-the-answer.md
@@ -22,7 +22,7 @@ Before onboarding, identify the observation that would support completion. Explo
### Two: governance costs work; measure performance through the real path
-Reading state, admission, validation, and writeback add work. Avoiding repeated execution and unnecessary wakes can reduce total cost. Measure single-turn latency and end-to-end completion separately; neither must necessarily get worse.
+Reading state, admission, validation, and writeback add work. Avoiding repeated execution and unnecessary wakes can reduce total cost. Measure single-turn latency and end-to-end completion separately.
A control plane does not directly make a model response faster. It may improve a journey whose delays come from rebuilding context, unattended waits, or repeated work.
@@ -32,7 +32,7 @@ A control plane does not directly make a model response faster. It may improve a
The [state substrate](state-substrate.md) owns work-lifecycle facts. LoopX also supports source-bound, scoped, revocable Agent preferences, alongside decision context, reward memory, and turn-recall capabilities or integration boundaries.
-This does not make arbitrary chats a permanent knowledge base. Preferences grant no action authority. Recalled content needs source, freshness, and scope checks; availability depends on release, configuration, and provider.
+Recalled content needs source, freshness, and scope checks; availability depends on release, configuration, and provider.
**Usage question:** are you retaining a Todo or receipt, an explicit user preference, or external knowledge material? Select its existing owner before deciding how to store and recall it, rather than putting every conversation in active state.
diff --git a/docs/book/en/chapters/08-extension-placement.md b/docs/book/en/chapters/08-extension-placement.md
index 719452de39..cf4055f9f8 100644
--- a/docs/book/en/chapters/08-extension-placement.md
+++ b/docs/book/en/chapters/08-extension-placement.md
@@ -198,8 +198,7 @@ lifecycle, keep it in the nearest owning module.
Suppose the current project needs to convert two internal states into one dict, with no external caller
and no independent version-compatibility requirement. Turning it into a Capability or Extension would
-add manifest, doctor, and upgrade cost. Shared code may justify a helper; it does not prove a need for
-independent installation and lifecycle.
+add manifest, doctor, and upgrade cost.
### 2. Provider for an existing Capability
@@ -211,7 +210,7 @@ The Provider can be:
- built-in: shipped with LoopX core;
- extension-delivered: supplied by an independent Extension.
-Accessing an external system is not the only test for an Extension. A connector that shares the core
+A connector that shares the core
release lifecycle and is always maintained by core can still be a built-in Provider.
### 3. New Capability
@@ -263,8 +262,7 @@ settle the outcome, then the owner, and only then the delivery shape.
### Where platform-level machinery belongs
One further branch confuses people. If the addition is only the registration and lifecycle machinery
-shared by every Extension, it belongs in `loopx/extensions/`, not in any provider package. It is not a
-capability and needs no manifest of its own. Putting that machinery inside one provider forces the next
+shared by every Extension, it belongs in `loopx/extensions/`, not in any provider package. needs no manifest of its own. Putting that machinery inside one provider forces the next
provider to depend on the first one's private structure.
## Record the minimum rationale
@@ -307,7 +305,7 @@ enables, and runs doctor themselves. A core built-in works as soon as LoopX is i
declared into a catalog read reports `declared=true, installed=false, enabled=false, ready=false`; it
does not become usable merely by existing.
-**Cost three: a public contract needs maintenance.** A new Capability needs a stable caller outcome, a real entrypoint, and validation. One Provider can satisfy these conditions. Independent installation alone is insufficient, and provider count is not a gate.
+**Cost three: a public contract needs maintenance.** A new Capability needs a stable caller outcome, a real entrypoint, and validation. One Provider can satisfy these conditions. Independent installation alone is insufficient.
**Boundary one: this decision governs ownership inside the LoopX product surface, not someone else's
repository layout.** An independently distributed provider lives in its own package or repository;
@@ -325,7 +323,7 @@ it go." Whether an outcome has value is answered by a Goal and its acceptance.
### "It calls an external API, so create a connector Capability"
-Transport is not the caller outcome. Find who needs the result and whether an existing Capability already
+Find who needs the result and whether an existing Capability already
owns it.
### "Declare `[[provides]]` now and add the caller later"
@@ -340,7 +338,7 @@ or managing resources is an effect and must go through a Capability or domain co
### "Several files share code, so make an Extension"
-Shared code may justify a helper. It does not prove a need for independent installation and lifecycle.
+Shared code may justify a helper.
Abstraction follows the change reason, not the file count.
## Placement used by this book
diff --git a/docs/book/en/chapters/09-extension-scaffold.md b/docs/book/en/chapters/09-extension-scaffold.md
index 06e35fe152..eaea4e38fd 100644
--- a/docs/book/en/chapters/09-extension-scaffold.md
+++ b/docs/book/en/chapters/09-extension-scaffold.md
@@ -2,7 +2,7 @@
Use a complete zero-permission teaching package to learn requests, responses, validation, and packaging. [Companion source](https://github.com/loopx-project/loopx/tree/main/packages/loopx-text-stats) in `packages/loopx-text-stats/` includes its manifest, Python package, two JSON Schemas, sample input, and standard-library tests.
-It is not a built-in Capability or default catalog entry and does not read or write Goals. The package owns text input and results; the existing Extension lifecycle owns installation, activation, and managed calls.
+Does not read or write Goals. The package owns text input and results; the existing Extension lifecycle owns installation, activation, and managed calls.
## Run the complete example first
diff --git a/docs/book/en/chapters/10-extension-lifecycle.md b/docs/book/en/chapters/10-extension-lifecycle.md
index 0744c42450..01e1d0b0a5 100644
--- a/docs/book/en/chapters/10-extension-lifecycle.md
+++ b/docs/book/en/chapters/10-extension-lifecycle.md
@@ -92,7 +92,7 @@ the origin of a `python_module`, and any view validator the extension declares.
invalidates the old doctor proof. LoopX's own built-in validators are deliberately excluded, so upgrading
LoopX does not invalidate every extension with it.
-Doctor status is a ladder rather than a boolean:
+Doctor status is a ladder:
```text
entrypoint_missing -> identity cannot be resolved
@@ -200,7 +200,7 @@ code keeps running. Install the package that matches the target revision around
actual behavior back with `run`. Activation state retains a bounded number of validated
revision snapshots (five today).
-`rollback_available=false` means no rollback revision is recorded, as after a first install. It is not a diagnosis of a damaged environment.
+`rollback_available=false` means no rollback revision is recorded, as after a first install.
If a target exists but its doctor fails, inspect or reinstall the matching package before rollback and doctor readback; when doctor passes, still confirm that the matching version is installed. Without a historical target, choose an explicit version and prepare an installation/upgrade path; repairing the environment cannot create history.
diff --git a/docs/book/en/chapters/11-engineering-boundaries.md b/docs/book/en/chapters/11-engineering-boundaries.md
index 8a838b67d0..af9a0e437d 100644
--- a/docs/book/en/chapters/11-engineering-boundaries.md
+++ b/docs/book/en/chapters/11-engineering-boundaries.md
@@ -217,5 +217,4 @@ Update theory chapters only when the public contract changes, not when internal
- [ ] Internal links and the public-boundary scan pass.
- [ ] The bilingual first screen has owner approval.
-Only after these checks should GitHub Pages publish from `main`. Pages is the display surface, not the source
-of content truth or LoopX state.
+Only after these checks should GitHub Pages publish from `main`. Pages is the display surface.
diff --git a/docs/book/en/chapters/12-control-plane-course.md b/docs/book/en/chapters/12-control-plane-course.md
index d91cc64235..930475a3de 100644
--- a/docs/book/en/chapters/12-control-plane-course.md
+++ b/docs/book/en/chapters/12-control-plane-course.md
@@ -206,7 +206,7 @@ The returned command yields `appended=false` and the debit count remains one. A
`settled` without `settlement_owed`; the next Turn no longer remains in that settlement-recovery path.
These assertions establish this internal recovery, not a zero supplier bill, resolution of another
-unknown effect, G1 closure, or Goal acceptance. Passing a test does not prove that a live Goal recovered.
+unknown effect, G1 closure, or Goal acceptance.
#### Next entrypoint and stopping condition {#settlement-next}
@@ -230,15 +230,13 @@ Should this Agent continue waiting? What changes with its own advancement or an
#### Factual basis {#monitor-facts}
Read current-Agent lane, selectable advancement, the Monitor's `consecutive_no_change`, `watch_only`,
-target, due state, and actual Host liveness. A busy peer does not supply facts for this lane. Receiving
-no notification does not prove no external change.
+target, due state, and actual Host liveness. A busy peer does not supply facts for this lane.
#### Why allow or refuse? {#monitor-reason}
This replan obligation depends on count, ownership, and selectable work together. Five is a particular
policy threshold, not a theorem about all waiting. Current-Agent advancement can preempt it, and
-explicit watch-only does not use the same trigger. No obligation does not establish an available waking
-Host or authorize mutation or delivery debit.
+explicit watch-only does not use the same trigger.
#### Supporting evidence {#monitor-evidence}
@@ -318,12 +316,12 @@ work.
[Authority](work-graph-and-authority.md), [recovery](04-runtime-boundaries.md), and the
[Workspace](workspace-v1.md) own the corresponding operating instructions. Owner decisions are not all
-authorized by automatic-Turn quota. An internal test run also does not establish this real CI result or approval.
+authorized by automatic-Turn quota.
Replace the task with a comparison report based on two public sources and the same reasoning applies:
material versions replace commits, methods and citation checks support findings, and an acceptor and
publication scope remain explicit. Recheck affected analysis after a source update; do not turn all old
-discussion into new evidence. A finished report does not authorize publication. This is conceptual transfer,
+discussion into new evidence. This is conceptual transfer,
not qualification of another product journey.
### Add one condition: the original Turn is not closed
diff --git a/docs/book/en/chapters/appendix-reference.md b/docs/book/en/chapters/appendix-reference.md
index 6d02b5f317..40e75e793f 100644
--- a/docs/book/en/chapters/appendix-reference.md
+++ b/docs/book/en/chapters/appendix-reference.md
@@ -1,6 +1,6 @@
# Terms and command entrypoints
-Use this appendix with an actual problem; the source course is not a prerequisite. Current installed `--help` owns command arguments. This page gives entrypoints and judgment conditions, not a complete CLI reference or automatic mutation permission.
+Use this appendix with an actual problem. Current installed `--help` owns command arguments. This page gives entrypoints and judgment conditions, not a complete CLI reference or automatic mutation permission.
## Read before deciding to change state {#read-before-change}
@@ -49,7 +49,7 @@ Public feedback should retain minimal reproducible versions, error codes and pub
| Evidence / Receipt | Support for a conclusion versus an accepted-operation record; both need correct binding |
| Kernel | Generic transition owner, not the owner of every external system's reality |
-See [state](state-substrate.md). Information in a prompt alone does not prove durable lifecycle writeback. Persisted chat also does not automatically become current authority.
+See [state](state-substrate.md). Persisted chat also does not automatically become current authority.
## Requirement two: identify interrupted work {#requirement-two-interruption-stops-at-identifiable-points}
@@ -114,7 +114,7 @@ loopx update apply
loopx doctor
```
-Confirm installation owner, target release and plan before authorizing apply. Ordinary users should not default to `--ref main`. Updating the CLI does not establish that every Host, Provider and existing Goal migrated. Recheck skills, state, Host readback and enabled Extension readiness for the surfaces actually used.
+Confirm installation owner, target release and plan before authorizing apply. Ordinary users should not default to `--ref main`. Recheck skills, state, Host readback and enabled Extension readiness for the surfaces actually used.
For backup, preview before execution:
diff --git a/docs/book/en/chapters/core-state-machines.md b/docs/book/en/chapters/core-state-machines.md
index 302c3ce1bd..95bad6537f 100644
--- a/docs/book/en/chapters/core-state-machines.md
+++ b/docs/book/en/chapters/core-state-machines.md
@@ -6,14 +6,13 @@ covered Todos, claims, and authority, and chapter 03 covered the transaction ord
This chapter is where they converge. Read in isolation, each mechanism holds up. The question here is
the one only this chapter can answer: **how do they connect back into a single loop?**
-The short answer is: **LoopX is driven by cooperating state-machine families, but its highest-level model
-is not “nine machines messaging one another.” It is one
+The short answer is: **LoopX is driven by cooperating state-machine families; its highest-level model is one
effectful Agent Loop.** The Harness interprets effect requests from an Agent or Host; bounded state
machines such as Todo, Gate, Quota, Settlement, and Scheduler then determine the legal action for their
part of the flow. They connect through durable facts, typed contracts, guarded transitions, and receipts
instead of overwriting each other's state.
-LoopX does not advance a Goal through one giant state machine. It assigns durable work, turn decisions,
+It assigns durable work, turn decisions,
evidence settlement, scheduling, and UI projection to state machines with explicit owners. This chapter
establishes vocabulary and abstraction levels first, explains why the design is split this way, shows the
cooperation loop, expands each state-machine family, and closes with the cost of the design. You can
@@ -79,7 +78,7 @@ validated observation becomes durable fact; and the receipt plus projection conn
for changing direction. They are not one whole-object Goal state, and one completed Todo is not Goal completion.
- **Facts and views — source / authoritative fact, derived decision, projection**: source is durable
owner-written fact; decision is the current rule result; projection is a view for an Agent, Host, or person.
- Not every displayed field is writable, and projection is not a second source of truth.
+ Not every displayed field is writable.
- **Action and proof — effect request / proposal, observation, transition, evidence, receipt**: proposal
requests an action; observation reports external fact; transition accepts legal change; evidence supports
a judgment; receipt proves an identified commit. A request is not authority, and a tool result is not
@@ -118,7 +117,7 @@ Collapsing these concerns into `Goal.status` or allowing an Agent to replace `Go
erase another Agent's progress. A network timeout would no longer say whether to retry, read back, or
compensate. Display fields would also drift into becoming sources of truth.
-Cooperation does not mean direct messaging. The nine state-machine families connect primarily through
+The nine state-machine families connect primarily through
four stable interfaces:
1. **Source facts**: reducers / interpreters read Todo, event, lease, Vision, and receipt facts.
@@ -147,7 +146,7 @@ flowchart TD
Facts -.-> Projection["projection Workspace / status"]
```
-This is not a sequence diagram in which state machine A calls state machine B. Source facts, typed
+Source facts, typed
decisions, effects, observations, and receipts are what pass between stages. Each machine owns only its
decision table and legal transitions.
@@ -282,8 +281,7 @@ This is why side effects are modeled separately: a model can change its mind, bu
be rolled back by editing context. Validation, version/identity guards, reconciliation, compensation events,
and replanning turn the error into another verifiable transition instead of an untraceable chat conclusion.
This idempotent-recovery guarantee has a precise boundary: it applies to settlement steps with a durable
-journal, an `effect_ref`, and a provider readback resolver. It is not a promise that every external tool
-call is automatically deduplicated. Settlement fails closed when the resolver is missing, raises, or
+journal, an `effect_ref`, and a provider readback resolver. Settlement fails closed when the resolver is missing, raises, or
returns an unknown state.
## How nine state-machine families compose one Loop
@@ -610,8 +608,7 @@ Todo, acceptance, or no-follow-up delta is `replan_noop` and cannot clear the ob
### Goal activation does not mean automation is enabled
The typed Goal activation source has only `active` and `stopped`. `active` means that the control plane
-may continue evaluation; it does not prove that a Host heartbeat is installed or that eligible work
-currently exists. Complete onboarding still proceeds through:
+may continue evaluation. Complete onboarding still proceeds through:
```text
project registered
@@ -639,7 +636,7 @@ transcript, or a local path breaks the public/private boundary.
## What makes LoopX a closed loop
-Closed-loop operation in LoopX is not “the Agent did something,” and it is not the same as `Todo=done`.
+
A more precise definition is: **the result of an effect is validated and written back to the authoritative
source that owns that fact, so the control plane can derive either the next legal action or a proven stop.**
If the result remains
@@ -789,7 +786,7 @@ therefore not a state you can decide on; it has to be proven item by item.
services, and extensions do not align to that number. What actually binds is the typed owner, the protocol
schema, and the transition rules.
-**Boundary two: this map does not replace the migration boundary.** The owner in the diagram and the
+The owner in the diagram and the
implementation language are separate dimensions. When a semantic is already carried by a TypeScript
owner, rebuilding it in Python from this teaching map creates a second source of truth.
@@ -798,8 +795,7 @@ durable journal, an `effect_ref`, and a provider readback resolver carry that gu
external call is not automatically deduplicated because this chapter mentions reconciliation; settlement
fails closed when the resolver is missing or returns an unknown state.
-**Boundary four: the diagram does not go to the front line.** The diagrams here explain; they are not an
-implementation spec. Before changing a rule, confirm the current typed owner, protocol schema,
+The diagrams here explain. Before changing a rule, confirm the current typed owner, protocol schema,
characterization fixture, and migration boundary.
## Named failures: where the handoff breaks
@@ -819,8 +815,8 @@ been replaced continuing to write. `needs_rebase` exists as the rejection path f
while the source stays unchanged. The symptom is a persistent UI/CLI disagreement that returns to the old
value on every refresh. Repair the source or builder, then read back.
-**Failure four: the reason to stop is not the same as closure.** A stopped Goal, paused quota, or blocked peer
-coordination can each stop polling; each is a legal stop, and none proves Goal closure. Only
+**Failure four:** A stopped Goal, paused quota, or blocked peer
+coordination can each stop polling; each is a legal stop. Only
`terminal_no_followup` means "stopped because validated Goal closure was derived." Collapsing them lets a
paused Goal look finished.
@@ -836,7 +832,7 @@ paused Goal look finished.
caller handles the rejection.
5. **Terminal is a conjunction.** Complete and closed Todo sources, no unresolved frontier, and a
structured `no_followup` intent must all hold.
-6. **A teaching map is not an implementation spec.** Change a rule only after confirming the typed owner,
+6. Change a rule only after confirming the typed owner,
protocol schema, characterization fixture, and migration boundary.
These six answer one question: **when the mechanisms are split across nine families that can only speak
diff --git a/docs/book/en/chapters/source-change-control-plane-rule.md b/docs/book/en/chapters/source-change-control-plane-rule.md
index 211b26f93e..5f3087f830 100644
--- a/docs/book/en/chapters/source-change-control-plane-rule.md
+++ b/docs/book/en/chapters/source-change-control-plane-rule.md
@@ -319,8 +319,7 @@ Replay executes the real decision path. It is more than a fixture-shape test.
### 5. Risk-based canary
For quota, scheduler, Todo/Gate, or Agent-facing output changes, let the canary planner select affected
-surfaces from the Git diff. Canary adds cross-boundary confidence. It does not replace the named focused
-regression.
+surfaces from the Git diff. Canary adds cross-boundary confidence.
## Step 8: Define failure and recovery
@@ -475,8 +474,7 @@ states, typed reasons, and ordered transitions.
**Fixing policy in the renderer.** Editing prose cannot repair a source or authority defect; conversely, policy
should not depend on Markdown strings.
-**Refactoring every adjacent module.** A protocol chain crossing several bounded contexts does not mean
-this PR should include every possible cleanup. Change only the complete chain this invariant requires.
+**Refactoring every adjacent module.** Change only the complete chain this invariant requires.
**Adding an empty adapter for a future Host.** An adapter without a real caller, capability, and receipt
only adds maintenance surface, and it looks like a shipped capability.
diff --git a/docs/book/en/chapters/source-protocol-map.md b/docs/book/en/chapters/source-protocol-map.md
index 04b86d5450..d7f2b4436e 100644
--- a/docs/book/en/chapters/source-protocol-map.md
+++ b/docs/book/en/chapters/source-protocol-map.md
@@ -32,7 +32,7 @@ developer job
-> current implementation and validation
```
-This chapter is a protocol-first source map. It is not a complete API catalog, and it does not ask you to memorize current function names. Its job is to help you identify the contract your Issue or PR will change.
+This chapter is a protocol-first source map. Its job is to help you identify the contract your Issue or PR will change.
## What you should learn
@@ -257,7 +257,7 @@ Protocols define cross-module contracts. Bounded contexts identify which change
| `handoff` | Cross-runtime handoff, review packets, and owner routes |
| `work_items` | Attention, selection, and operator-facing work read models |
-On the `v0.5.4` migration baseline, bounded context and implementation language are separate dimensions. Complete transactions under `goals`, `todos`, `quota`, `scheduler`, `work_items`, and `turn_driver` now have TypeScript semantic owners. Examples include Vision refresh, the local task-lease lifecycle, quota spend/void/monitor-poll commit, and receipt-bound scheduler follow-up. Adjacent Python facade modules may serve only as CLI transport, legacy projection, an explicit external Provider or Host effect, or writeback that has not migrated. Read the shipped baseline in the [TypeScript Control-Plane Migration RFC](/loopx/docs/architecture/rfcs/typescript-control-plane-migration-v0/) and trace the active request handler and caller before assigning ownership. A Python entrypoint does not prove that Python still owns the decision.
+On the `v0.5.4` migration baseline, bounded context and implementation language are separate dimensions. Complete transactions under `goals`, `todos`, `quota`, `scheduler`, `work_items`, and `turn_driver` now have TypeScript semantic owners. Examples include Vision refresh, the local task-lease lifecycle, quota spend/void/monitor-poll commit, and receipt-bound scheduler follow-up. Adjacent Python facade modules may serve only as CLI transport, legacy projection, an explicit external Provider or Host effect, or writeback that has not migrated. Read the shipped baseline in the [TypeScript Control-Plane Migration RFC](/loopx/docs/architecture/rfcs/typescript-control-plane-migration-v0/) and trace the active request handler and caller before assigning ownership.
Ask:
@@ -296,7 +296,7 @@ Treat repository routes as owners, not as automatic placement from a directory n
| Operator projection | Status, frontstage, or projection owner; a renderer only consumes the typed model |
| Documentation and validation | Owning protocol document, `tests/`, `examples/`, or a public-safe fixture |
-Current capability packages own their documentation and register through `catalog_entry.py`. Before contributing, run `loopx capability list --format json` and `loopx capability show --format json` to confirm that the capability is registered and to read its entry commands, Provider boundary, and durable validation. A directory or README alone does not prove that a capability is shipped.
+Current capability packages own their documentation and register through `catalog_entry.py`. Before contributing, run `loopx capability list --format json` and `loopx capability show --format json` to confirm that the capability is registered and to read its entry commands, Provider boundary, and durable validation.
Code under `loopx/capabilities//` is not automatically a public Capability; it still needs explicit registration and a real caller contract. `loopx/extensions/` is not a bucket for every external integration; it owns generic Extension lifecycle, while an independently versioned Provider belongs in its delivery package. Keep private helpers with the nearest owner instead of promoting them to a Capability or Extension merely because they span several files.
@@ -474,7 +474,7 @@ Before entering the source, confirm these hold on their own:
1. **The owner of a rule is the module that decides legal transitions, not the module that first prints words about it.** If you cannot name the protected invariant, the change is not yet located.
2. **A PR description carries one complete causal chain: source, invariant, decision, projection or effect, receipt, validation.** A slice that can only list function names cannot be reviewed.
3. **Documents describe responsibility ownership; code describes current behavior.** When they conflict, pick the authority by conflict type and make this PR update the other side.
-4. **Code under `loopx/capabilities//` does not prove the Capability is shipped.** Registration plus a real caller contract is the release test; verify with `loopx capability list --format json`.
+4. Registration plus a real caller contract is the release test; verify with `loopx capability list --format json`.
5. **Placement precedes implementation.** The capability id, provider id, and built-in or extension-delivered choice come with a written reason before the first line of code.
6. **Tasks come from public entrypoints.** Public Contributor Tasks, Issues, and fixtures are the only source of work you can participate in; live active state and maintainer-local judgment are not.
diff --git a/docs/book/en/chapters/source-trace-protocol-chain.md b/docs/book/en/chapters/source-trace-protocol-chain.md
index 0a826cd289..943bdd380a 100644
--- a/docs/book/en/chapters/source-trace-protocol-chain.md
+++ b/docs/book/en/chapters/source-trace-protocol-chain.md
@@ -226,7 +226,7 @@ For this scenario:
- `repair-link-checker` remains runnable;
- the Gate remains visible in the user channel.
-This is not a Gate bypass. The selected fallback never performs the protected action.
+The selected fallback never performs the protected action.
### Ordered policy, not scattered booleans
@@ -491,7 +491,7 @@ For a control-plane failure, verify in order:
After a trace, these should hold on their own:
1. **Every renamed or redefined field comes with a full consumer list.** Updating producers alone is incomplete, and a missing-field fallback counts as a consumer.
-2. **Success at every layer is not evidence that the chain is correct.** The test is the first boundary that violates the invariant, not the final return value.
+2. The test is the first boundary that violates the invariant, not the final return value.
3. **A missing field's default participates in the decision.** So the contract must state whether absence means reject, repair, or compatibility fallback.
4. **Authority has exactly one canonical source.** Several places may read a field and only one owns it; mistaking a reader for the owner is the most common leftover from a cross-layer change.
5. **Judging authority follows the protocol document; judging current behavior follows the source.** When they conflict, pick by conflict type and make this change update the other side.
diff --git a/docs/book/en/chapters/source-validation-to-pr.md b/docs/book/en/chapters/source-validation-to-pr.md
index 73824ff458..ccaefa6cc2 100644
--- a/docs/book/en/chapters/source-validation-to-pr.md
+++ b/docs/book/en/chapters/source-validation-to-pr.md
@@ -64,8 +64,7 @@ ambiguous scope -> typed repair
explicit global scope -> global Gate
```
-This layer is the closest proof of an invariant. It does not prove that CLI, projection, and scheduler are
-connected correctly.
+This layer is the closest proof of an invariant.
### 2. Focused deterministic smoke
@@ -555,7 +554,7 @@ semantic core. The final `APPROVE` applies only to the revalidated exact head.
## Distinguish merge, release, deployment, and observation
-A merged PR does not prove a release, deployment, or every external Host update. Follow-up may include:
+Follow-up may include:
- full-public smoke on `main`;
- release qualification;
diff --git a/docs/book/en/chapters/state-substrate.md b/docs/book/en/chapters/state-substrate.md
index 9433bf28ab..330c1958e4 100644
--- a/docs/book/en/chapters/state-substrate.md
+++ b/docs/book/en/chapters/state-substrate.md
@@ -133,7 +133,7 @@ Delivery remains writer-specific. Check the actual command, authority mode, and
Shared-authority work in `v0.5.4` introduced a provider-neutral TypeScript `AuthorityStore` contract and candidate-provider validation. Later local cutover, fencing, projections, and default-entry adoption have separate milestones.
-Historical capabilities are not evidence that current paths stop at that baseline, nor that candidate qualification delivers a remote service. Read the selected Goal to establish its current File/SQLite authority path.
+ Read the selected Goal to establish its current File/SQLite authority path.
Staged candidates such as NoKV/PostgreSQL do not acquire runtime authority automatically. Installing a Provider also does not change an existing Goal's source of truth.
diff --git a/docs/book/en/chapters/work-graph-and-authority.md b/docs/book/en/chapters/work-graph-and-authority.md
index cf7b840c09..8d4265e50c 100644
--- a/docs/book/en/chapters/work-graph-and-authority.md
+++ b/docs/book/en/chapters/work-graph-and-authority.md
@@ -44,7 +44,7 @@ Owner operations have lifecycle authority; automated work has quota admission. C
## Claims, leases and current execution proof
-`handoff_mode` determines applicable constraints. Default `legacy` retains soft-claim/hard-lease compatibility; `soft_claim` and `hard_lease` have their own rules. Some legacy terminal paths can return `terminal_fence_not_required`. A regression in one mode is not proof of strong exclusion across every writer.
+`handoff_mode` determines applicable constraints. Default `legacy` retains soft-claim/hard-lease compatibility; `soft_claim` and `hard_lease` have their own rules. Some legacy terminal paths can return `terminal_fence_not_required`.
Promoted File/SQLite authority reads from the selected provider rather than falling back to old lease files. Source selection, registration and current Todo eligibility participate alongside the lease. `task-lease inspect` is an observation, not a lock held across subsequent work.
@@ -93,7 +93,7 @@ Handoff is more than sending a message. A recipient must know which work was rec
**Sixth, return the result to its acceptor.** T3 reassesses current artifacts and decisions. Message delivery, recipient input adoption, work acceptance, publication permission and actual external delivery each require appropriate evidence. None alone establishes the whole chain.
-This six-step teaching case does not claim automatic coordination across every Host, device or repository. Qualify the relationships the user actually needs.
+Qualify the relationships the user actually needs.
## Workspace isolation is not integrated correctness {#parallel-editing}
diff --git a/docs/book/en/chapters/workspace-v1.md b/docs/book/en/chapters/workspace-v1.md
index f790554ac2..70c65a9374 100644
--- a/docs/book/en/chapters/workspace-v1.md
+++ b/docs/book/en/chapters/workspace-v1.md
@@ -36,11 +36,11 @@ The Workspace presents and initiates governed actions, but Goal, Todo, Gate, eve
- **HTTP success is not write completion.** A request being accepted and an action completing are two different things, and the second may be stopped by a Gate or rejected by a stale check.
- **A button is not an independent authority.** Goal stop/resume checks owner authority and the reviewed fingerprint; Todo actions use lifecycle rules; quota governs eligibility for automated Turns.
-The whole chapter compresses into one sentence: **the Workspace is where you observe and initiate; it is not a new source of truth.**
+The whole chapter compresses into one sentence: **the Workspace is where you observe and initiate.**
## Confirm the runtime before trusting the page
-A page appearing does not mean the control plane is healthy. Check version and diagnostics before starting or reusing the service; `dashboard --no-open` is not merely a state query:
+Check version and diagnostics before starting or reusing the service; `dashboard --no-open` is not merely a state query:
```bash
loopx --version
@@ -148,7 +148,7 @@ After configuring, read back the Goal, Agent, Topic, ingress mode, Session bindi
loopx lark-inbox drain --goal-id --agent-id
```
-Disconnect removes only that Goal's Topic route; it does not delete the Goal, Session, history, or other connections. A message arriving also does not mean the Agent gained send, repository-write, or production permission; those actions still pass through their own Gates and Provider readback.
+Disconnect removes only that Goal's Topic route; it does not delete the Goal, Session, history, or other connections. those actions still pass through their own Gates and Provider readback.
## One-off generation and continuous delivery are two authorization chains
@@ -160,7 +160,7 @@ loopx periodic-report inspect-profile --preset weekly --format json
`active` and `generation_allowed` in the receipt should both be `true`. The built-in weekly profile has no schedule and no sink, so **one generation creates no recurring task and sends no message**.
-Continuous reporting is a separate authorization chain: a custom profile declares the cadence, Host Automation performs the waking, and `enabled: true` on a machine or Goal subscription together with an explicit `route_ref` constitutes continuous-delivery authority. Pausing the Automation, disabling the profile, or closing the subscription stops the corresponding path. A successful generation does not mean a successful external send; the Provider, sending identity, route, and message readback each still need verification.
+Continuous reporting is a separate authorization chain: a custom profile declares the cadence, Host Automation performs the waking, and `enabled: true` on a machine or Goal subscription together with an explicit `route_ref` constitutes continuous-delivery authority. Pausing the Automation, disabling the profile, or closing the subscription stops the corresponding path. the Provider, sending identity, route, and message readback each still need verification.
## Cost and boundary
@@ -170,7 +170,7 @@ Continuous reporting is a separate authorization chain: a custom profile declare
**Cost three: four kinds of "enabled" must be distinguished.** Collapsing them into one switch misjudges capability availability, and keeping them apart carries real mental overhead.
-**Boundary one: the Workspace does not own facts.** A broken UI proves neither a healthy control plane nor stopped execution. Distinguish source, runtime and projection first. Only after confirming source and execution conditions can the fault be limited to display recovery, not manual state edits through the UI. It also does not constitute Stage 2C authority — qualification and promotion of a shared-authority provider come from separate shadow and conformance work, not from the existence of an operator surface.
+Distinguish source, runtime and projection first. Only after confirming source and execution conditions can the fault be limited to display recovery, not manual state edits through the UI. qualification and promotion of a shared-authority provider come from separate shadow and conformance work.
**Boundary two: desktop updates are narrowly scoped.** Updates can only come from the fixed official feed; macOS uses updater signature and ad-hoc code signing and should not be described as notarized. Restoring a previous version also does not promise to reverse a future-incompatible Goal schema.
@@ -190,10 +190,6 @@ For one Workspace acceptance pass, confirm at least that:
## Invariants
-1. **The UI is a projection, not a source of truth.** Re-read the source before any consequential judgment.
-2. **HTTP success does not prove the write completed.** Only a receipt and readback do.
-3. **A click is not authorization.** Goal lifecycle accepts owner operations, Todo lifecycle checks work transitions, and the current quota contract admits automated Turns. The page grants none of these permissions.
-4. **The four kinds of "enabled" need separate evidence.** They may be prerequisites for one another; one switch does not establish that every condition holds.
-5. **A message arriving does not widen permission.** Neither capture scope nor ingress mode grants new write authority.
-
-These five answer one question: **when the interface tells you everything is fine, what makes that believable?**
+1. **The UI is a projection.** Re-read the source before any consequential judgment.
+3. Goal lifecycle accepts owner operations, Todo lifecycle checks work transitions, and the current quota contract admits automated Turns. The page grants none of these permissions.
+4. **The four kinds of "enabled" need separate evidence.** They may be prerequisites for one another.
diff --git a/docs/book/en/index.md b/docs/book/en/index.md
index 8567677d75..4778f3006c 100644
--- a/docs/book/en/index.md
+++ b/docs/book/en/index.md
@@ -45,8 +45,7 @@ waits for CI, crosses sessions, changes owners, encounters approval gates, and r
LoopX keeps the goal, work queue, authority, evidence, and recovery conditions in a project-owned control
plane.
-This book is not a copy of the LoopX CLI reference, and it does not assume that you want to contribute to
-the Kernel. It gives external developers a stable path for deciding:
+It gives external developers a stable path for deciding:
- whether a task needs only one session, a persistent Host goal, or a project-level control plane;
- when Todo, Gate, Evidence, Quota, monitor, and recovery contracts add real value;
@@ -72,7 +71,7 @@ source change. Contributions are not limited to Kernel maintainers, and the Cour
mechanism model further into implementation, rules, and validation. You can work on the Control Plane,
Capabilities and Domain State, Providers, Host or Runner integration, projections, documentation and
fixtures, or Extension and package lifecycle. An Extension is one delivery choice for independently
-versioned or optional functionality, not the default shape of every contribution.
+versioned or optional functionality.
## Current validation baseline
@@ -84,11 +83,11 @@ versioned or optional functionality, not the default shape of every contribution
The official public protocols remain authoritative for protocol facts. Commands that change across
releases remain authoritative in the release you use, its current `--help`, and official documentation.
-This book owns the learning path and explanatory model, not another complete command reference.
+This book owns the learning path and explanatory model.
In `v0.5.4`, key semantics for the Effect Program, Turn settlement, Todo completion, quota delivery
routing, workspace causality, and scheduler state sit behind typed TypeScript owners. During the
migration, the Python CLI still owns transport, legacy projections, external Provider calls, and some
-durable writeback. These are not two independently evolving control planes. Treat the
+durable writeback. Treat the
[TypeScript Control-Plane Migration RFC](/loopx/docs/architecture/rfcs/typescript-control-plane-migration-v0/)
-on current `main` as the direction for later stages, not as shipped `v0.5.4` behavior.
+on current `main` as the direction for later stages.
diff --git a/docs/book/en/welcome-wagon.md b/docs/book/en/welcome-wagon.md
index e392465b86..7b32124bfe 100644
--- a/docs/book/en/welcome-wagon.md
+++ b/docs/book/en/welcome-wagon.md
@@ -239,7 +239,7 @@ A first review can answer only six questions:
Cross-direction questions may enter an
[Open Strategy Review](/loopx/docs/community/open-strategy-reviews/). It produces a disposition, owner,
-next artifact, and review trigger; it does not replace the RFC, Issue, or PR path with a meeting vote.
+next artifact, and review trigger.
## Ask For Help Without Losing The Signal {#ask-for-help}
diff --git a/docs/book/index.md b/docs/book/index.md
index 6c2aa7f13f..9a1c91f4bd 100644
--- a/docs/book/index.md
+++ b/docs/book/index.md
@@ -41,7 +41,7 @@
交接、等待和外部状态变化。LoopX 把这些过程中的目标、工作队列、权限、证据和恢复条件
放进项目拥有的控制面。
-本书不复制 LoopX CLI reference,也不要求读者成为 Kernel 核心贡献者。它提供一条稳定的
+它提供一条稳定的
学习路径,让外部开发者能够判断:
- 当前任务只需要一次普通会话,还是需要持久 Goal;
@@ -74,11 +74,10 @@ Extension 只是可独立版本化和交付的一种路径。
- 运行时前提:Python 3.11+ 与 Node.js 22.22.3+。
协议解释以 LoopX 官方公开合同为事实源。易变化的命令仍以对应发布物、官方文档和当前
-`--help` 为准;本书负责教学顺序与心智模型,不成为另一份完整命令参考。
+`--help` 为准;本书负责教学顺序与心智模型。
`v0.5.4` 已把 Effect Program、Turn settlement、Todo completion、quota delivery routing、
workspace causality 与 scheduler state 等关键语义放到 typed TypeScript owner 后面。Python CLI
-仍负责迁移期 transport、兼容投影、外部 Provider 调用和部分持久化写回;这不是两套可独立演进的
-控制面。当前 `main` 的后续迁移阶段以
+仍负责迁移期 transport、兼容投影、外部 Provider 调用和部分持久化写回。当前 `main` 的后续迁移阶段以
[TypeScript Control-Plane Migration RFC](/loopx/docs/architecture/rfcs/typescript-control-plane-migration-v0/)
为准,不应倒推为 `v0.5.4` 已发布行为。
diff --git a/docs/book/welcome-wagon.md b/docs/book/welcome-wagon.md
index 8a38b2859f..5a7201db0c 100644
--- a/docs/book/welcome-wagon.md
+++ b/docs/book/welcome-wagon.md
@@ -260,5 +260,5 @@ problem
- 想修改 LoopX:读[开发者贡献地图](chapters/source-protocol-map.md);
- 想深入 Kernel:进入 [Control-Plane Developer Course](chapters/12-control-plane-course.md)。
-完成一条路线以后再选择下一条。Welcome Wagon 的目标不是让新人一次理解所有东西,而是让第一
+完成一条路线以后再选择下一条。Welcome Wagon 的目标是让第一
次真实行动足够安全、可验证,并且能被社区接住。
diff --git a/docs/concepts/interaction-pattern-catalog.md b/docs/concepts/interaction-pattern-catalog.md
index 273fb01aa6..ca9d49259d 100644
--- a/docs/concepts/interaction-pattern-catalog.md
+++ b/docs/concepts/interaction-pattern-catalog.md
@@ -2700,7 +2700,7 @@ keep "we stopped supporting this" from becoming "this was never configured".
(`loopx/control_plane/coordination/local_authority_shadow.ts:57`) rather than
disappearing into a transport error, because a rejection that looks like a
transient failure invites a retry loop.
-3. **Clearing is neither enable nor bootstrap.** One setting is retired; the
+3. One setting is retired; the
replacement capture path is configured on its own terms.
`apply_coordination_shadow_changes` is documented as "Clear retired settings
and configure the transaction-bound shadow independently"
diff --git a/docs/development/README.md b/docs/development/README.md
index 616e105bb5..f9c5f5e970 100644
--- a/docs/development/README.md
+++ b/docs/development/README.md
@@ -226,14 +226,12 @@ compliance and live effects. Existing sessions may retain an older copy.
Run `uv run --extra test python -m pytest -q tests/test_repository_instruction_delivery.py`
for root size, shared import, local routes and existing inbound anchors. Review
a moved obligation clause by clause: owner, modality, scope, order, exceptions,
-evidence provenance, continuation and stop conditions. A link test or shorter
-file does not establish equivalence. Keep operational rules in their existing
+evidence provenance, continuation and stop conditions. Keep operational rules in their existing
owners rather than adding another parallel policy collection.
Design sources and the disposition of the earlier proposal are recorded in
[the instruction/skill/prompt study](../research/2026-10-17-agent-instruction-skill-prompt-guidance.md).
-
### Progressive Context For Development
The default working context should answer the current decision: the accepted goal,
@@ -278,7 +276,7 @@ Existing sessions may retain old instructions; source edits alone do not prove
native startup adoption or agent compliance.
For product context delivery, selection, continuation and replanning have different
-information needs. A suggested `selected_todo` is not proof of an actual work choice.
+information needs.
A qualified continuation can retain the bound work in full and make other candidates
discoverable with exact details; a new choice must inspect what that choice needs.
Do not implement this by filtering a full-required response in the caller. Change
@@ -305,10 +303,9 @@ and unknown model cost/adoption rather than inferring benefit from fewer bytes.
日志和完整证据在核验、争议、重规划、收口等需要它们的环节展开。默认仍显示相关
失败或过期信号;验收声明必须读取对应证据,索引和旧 Agent 结论不代替核验。
入口指引保留核心义务,详细流程以明确触发条件链接,不急切加载全部文档/Skill。
-移动指导须保留主体、顺序、义务强度、范围、例外和停止条件;源文件更新不证明
-当前宿主已加载,也不证明模型实际遵从。
+移动指导须保留主体、顺序、义务强度、范围、例外和停止条件;
-产品侧按选择、继续执行、重规划区分需要的信息;`selected_todo` 不证明模型已选择。
+产品侧按选择、继续执行、重规划区分需要的信息;
合格的已绑定任务接续可保留当前工作全文和其他候选的可发现入口,但不能在仍要求
全读的接口外手动裁剪。范围 owner、必读指引、详情接口、实际输入及恢复绑定应一起
替换;未交付正文不能进入保留基线,丢失上下文须恢复原决定而非重新准入。
diff --git a/docs/development/bugs/workspace-status-access-errors.md b/docs/development/bugs/workspace-status-access-errors.md
index 2787b6cf0d..2919e4e950 100644
--- a/docs/development/bugs/workspace-status-access-errors.md
+++ b/docs/development/bugs/workspace-status-access-errors.md
@@ -39,7 +39,7 @@ HTTP 仍为 **500**;固定公开错误文案不变,仅增加:
- 异常链最多检查 8 个节点,按对象身份去环;显式 `__cause__` 优先。
仅 `EffectRuntimeStartupError` 的 `runtime_launch_failed` /
`runtime_request_failed` 允许沿未抑制的隐式 `__context__` 查找权限原因。
- 普通历史 context、`raise ... from None` 不构成权限证据。
+ 普通历史 context 分支停止分类;`raise ... from None` 抑制的隐式 context 也在此停止。
前端只在 HTTP >= 500 时识别该结构化错误码。错误体按实际字节最多读取 16 KiB,
不信任 Content-Length;复用单次请求的 30 秒超时。读完、超限或取消后释放读取器。
@@ -64,7 +64,7 @@ Chat 操作、审批、状态机、Goal 注册信息和文件权限均不改动
## 仍未细分的故障
`service` 仍可包含注册数据解析、依赖/安装、运行时启动、通信/协议、非权限结构化
-I/O、未知投影异常及上游 5xx。这不是封闭的运行时枚举,也不是每项均实机复现。
+I/O、未知投影异常及上游 5xx。
依据见 [registry.py](../../../loopx/registry.py) 与
[collection.py](../../../loopx/control_plane/status/collection.py)。
仅当异常最终形成逐 Goal 请求的 5xx 才进入此提示;内部已处理的健康诊断不在本范围。
diff --git a/docs/development/ci-impact-selection.md b/docs/development/ci-impact-selection.md
index 1d257804a8..bd028eb2f9 100644
--- a/docs/development/ci-impact-selection.md
+++ b/docs/development/ci-impact-selection.md
@@ -47,7 +47,7 @@ Frontstage Pages 只验收并发布公共网站和 projection demo,保留构
仍由 Python Tests 承担。新合并不会中断正在运行的正式发布,只替换等待中的下一次
发布;同一 PR 的旧验证仍会取消。
-本方案不是为每类 PR 维护一套测试清单,而是明确重型 job 的职责。纯前端变化不需要
+本方案是明确重型 job 的职责。纯前端变化不需要
重跑后端持久化与崩溃恢复矩阵,但前端自己的实际构建与浏览器验收成为必需项。
预算、静态宿主 prompt 和后端 Python/TS 逻辑暂不享受免跑;它们仍可能改变核心行为。
新增一种豁免只需审阅其业务边界和保留的验收,不要求列举全部替代测试文件。
@@ -78,8 +78,7 @@ remain required by `checks`, as does the static lane. The existing `pytest` and
`merge-gate` still reject any required failure, skip or missing coverage. This
removes the full browser/TypeScript wait from Python's critical path, but allows
up to six already-bounded Python jobs to overlap those lanes; a later browser
-failure may now coexist with running Python tests. It neither reserves hosted
-capacity nor proves a throughput improvement. `ci:full` selects all qualification,
+failure may now coexist with running Python tests. `ci:full` selects all qualification,
without overriding failed admission; use a manual run for complete diagnostics
of a failing revision. Older queued workflow versions keep their own policy.
@@ -152,8 +151,7 @@ worker 秒数、各阶段总和与最慢用例。缺失、损坏或矛盾记录
断言结构;子测试单独保留失败位置,不重复计时。新增 JSON 不含消息、参数、locals 或
捕获的 IO,原 pytest 输出不变。未知类、缺失源码或诊断异常仍是证据缺口;未送达的
报告与收集失败不在覆盖范围,不能据此完成原因归因、证明真实性或豁免完整门禁。
-并发 phase 总和不是
-runner-minutes、排队时长或 CPU 时间;不完整记录仅给出下界,环境准备与占用须结合
+不完整记录仅给出下界,环境准备与占用须结合
job/step 时间戳。记录不进入 timing cache、不改变测试选择、不替代门禁;没有耗时
历史时仍按原等权规则分片。
完整 pytest node id 用 SHA-256 标识;显示名去除参数内容并限制为 256 字符。
@@ -195,7 +193,7 @@ describes the workflow topology, not how many jobs actually ran.
`python_shards` 从 `checkout_sha` 对应的不可变 workflow 读取静态分片轴,当前为六片,
不另存历史计数;不支持或不连续的拓扑直接报错,不输出猜测值。文档/前端豁免仍为零。
-它描述 workflow 拓扑,不能证明任何分片实际执行或 JUnit/coverage 已完整。
+它描述 workflow 拓扑。
The merge gate requires
success for required jobs and an explicit skip for exempt ones; failure,
@@ -294,7 +292,7 @@ coverage command runs only in shard 1, whose `lcov.info` the existing merger
already consumes; browser coverage and acceptance receipts remain required from
all three shards. The merger rejects missing unit coverage or incomplete browser
acceptance. This removes two duplicate unit-coverage invocations per full or
-presentation run; it does not establish a hosted wall-time improvement.
+presentation run.
旧 PR 清理独立为 CI Maintenance,保留原有来源与 head 校验,也不执行 PR 代码。
清理成功不再显示为一次 Python Tests 成功。Dashboard 的单元覆盖率只在第 1 片
diff --git a/docs/development/contributor-tasks.md b/docs/development/contributor-tasks.md
index b47884b69f..d6ef50eb55 100644
--- a/docs/development/contributor-tasks.md
+++ b/docs/development/contributor-tasks.md
@@ -66,8 +66,7 @@ contributors by anchored rows.
For first-review contacts, accepted subsystem owners and voluntary scope
confirmation, use the [governance review roster](../../.github/GOVERNANCE.md#first-review-responsibilities).
-Request the closest contact before escalating to the lead maintainer. A
-preferred review contact is not an exclusive task claim or new merge authority.
+Request the closest contact before escalating to the lead maintainer.
1. Prefer a linked GitHub issue. If there is no issue yet, open one with the
contributor task template; it asks for the anchor and the gap.
@@ -81,8 +80,7 @@ preferred review contact is not an exclusive task claim or new merge authority.
there is a public helper slice instead.
Before claiming a row, reconcile its anchor with latest main, related PRs and
-the roadmap. Historical rows are not proof that a missing feature remains
-unimplemented or a proposed slice is still useful. The
+the roadmap. The
[Technical Directions map](../project/technical-directions.md) owns contributor
routing and current maturity; this board does not keep a second copy.
diff --git a/docs/development/control-plane-course/00-concept-primer.md b/docs/development/control-plane-course/00-concept-primer.md
index 03c875f29b..4f76ebb4ac 100644
--- a/docs/development/control-plane-course/00-concept-primer.md
+++ b/docs/development/control-plane-course/00-concept-primer.md
@@ -28,7 +28,7 @@ session 结束、模型切换、Agent 交接和外部世界变化。完整 trans
| 何时再看,何时停止? | 周期唤醒会热轮询,空 todo 也可能误停 | monitor、scheduler hint、backoff、terminal audit |
| 失败或换人后从哪里继续? | transcript 不能提供稳定 identity 和幂等边界 | event、run history、lineage、replay、repair |
-外置状态不是把 transcript 原样搬到磁盘。它只保存下一轮重建正确决定所需的紧凑事实,旧推理
+外置状态只保存下一轮重建正确决定所需的紧凑事实,旧推理
可以丢弃,当前环境必须重探测。
### 长程质量同时包含“跑稳”和“跑好”
@@ -74,7 +74,7 @@ Kanban is the picture; the control plane is the contract.
## 从普通对话、原生 Goal 到 LoopX
-理解 LoopX 最容易的方法,不是先背模块,而是看控制信息逐层外置:
+理解 LoopX 最容易的方法:
| 形态 | 外置了什么 | 擅长解决什么 | 仍未覆盖什么 |
| --- | --- | --- | --- |
@@ -83,13 +83,11 @@ Kanban is the picture; the control plane is the contract.
| LoopX control plane | 结构化 canonical state,以及由它派生的每轮 CLI packet | 跨 session、Agent、host 和外部系统组织可审计的长期生命周期 | 领域判断、模型推理和外部系统本身的正确性 |
Codex 的自动化基线通过 `thread/goal/set` 持久化 objective/status,通过
-`thread/goal/get` 读回,再用 `turn/start` 继续执行。交互式 `/goal` 是可见的人工入口;仅把
-`/goal` 写在普通 prompt 开头,不等于已经建立了持久 Goal。原生 Goal 的关键价值,是把“这次
+`thread/goal/get` 读回,再用 `turn/start` 继续执行。交互式 `/goal` 是可见的人工入口。原生 Goal 的关键价值,是把“这次
对话要做什么”提升成 host 可持续维护和判断的 goal lifecycle。抽象来看,它提供的是一个
稳定 objective,加上 host 对继续、暂停、预算受限或完成的结果判断。
-Host 可以自行安排后续 Turn,模型也可以在执行中调整方案;这仍不等于项目已经拥有 typed
-scheduler ACK 或 replan delta。区别不在于系统“会不会再跑、会不会改计划”,而在于 cadence、
+Host 可以自行安排后续 Turn,模型也可以在执行中调整方案;区别不在于系统“会不会再跑、会不会改计划”,而在于 cadence、
路线变化及其证据是否成为跨 host、跨 Agent 可重放的结构化事实。
LoopX 不否定这层能力,而是继续外置两层:
@@ -114,7 +112,7 @@ objective · lifecycle goal · todo · authority · quota · evidence · rec
host/runtime executes the current Turn
```
-CLI packet 不是第二份 canonical state,也不是把所有历史塞回 prompt。它是带版本、lineage 和
+CLI packet 是带版本、lineage 和
下一步命令的当前决策投影;下一 Turn 必须重新读取并重新生成,不能靠模型记住上一份 packet。
Host 中长期保留的是稳定的 re-entry body:它只说明怎样找到 goal、调用 LoopX CLI 并取得
当前 packet,不承载某一轮的 packet 内容。
@@ -183,11 +181,11 @@ flowchart LR
- **Capability:** 负责归一化事实、验证结果并提出有限的 typed transition;
- **Kernel:** 负责接受或拒绝 transition,并持久化 todo、gate、monitor、writeback、quota 与调度。
-Domain State、evidence 和 receipt 是这些角色之间传递的工件,不是新的 owner。Extension
-则是 provider 的交付和生命周期边界,也不是第五种运行责任。Host/runtime 承载 session、
+Domain State、evidence 和 receipt 是这些角色之间传递的工件。Extension
+则是 provider 的交付和生命周期边界。Host/runtime 承载 session、
工具和调用,同样不新增领域 decision owner。
-这不是一条永远顺利的流水线。每次 writeback 后,Kernel 都要根据新事实重新决定:
+每次 writeback 后,Kernel 都要根据新事实重新决定:
```text
continue | wait | ask | replan | repair | terminal
@@ -281,7 +279,7 @@ Agent 是控制面身份,不等同于某个固定模型或进程。更换 runt
### Turn 是一次有界动作
**Turn** 从一份带版本和 lineage 的只读 snapshot 开始,完成一个有界判断或动作,返回 typed
-result。它不是整个长期任务。
+result。
一次 Turn 可以:
@@ -307,8 +305,7 @@ canonical state + fresh environment
```
Packet 要足够薄,只携带本轮 identity、允许动作、必要 gate、验证条件和 writeback 命令;但又
-不能薄到遗漏 required proof、scope 或 terminal gap。Packet 的压缩质量因此是控制面正确性的一部分,
-不是单纯的 prompt 优化。
+不能薄到遗漏 required proof、scope 或 terminal gap。Packet 的压缩质量因此是控制面正确性的一部分。
### Scheduler 与 heartbeat 只负责“何时再看”
@@ -337,7 +334,7 @@ Kernel 提议下一次 cadence
| Lease | 当前执行窗口是否被占用,何时过期? | 短期、可续租、可回收 |
| Gate | 哪个 scoped decision 尚未满足? | 由对应 authority 明确解决 |
-Claim 不自动授予生产写权限,lease 不代表长期 ownership,普通 user todo 也不自动冻结整个 goal。
+Claim 不自动授予生产写权限。
Gate 必须带清晰 scope;若 scope 缺失,应修复投影或状态,而不是猜测它约束所有 Agent。
### Authority 决定谁能提交哪种 transition
@@ -394,7 +391,7 @@ Agent 持续违反运行协议时,**self-repair** 修的是系统规则、状
## 人的干预怎样真正改善下一轮
-人工输入不是一种统一的“反馈字段”。它对生命周期的含义不同,必须写入对应的结构:
+人工输入对生命周期的含义不同,必须写入对应的结构:
| 人工输入 | 正确落点 | 对下一轮的影响 |
| --- | --- | --- |
@@ -404,7 +401,7 @@ Agent 持续违反运行协议时,**self-repair** 修的是系统规则、状
| “以后这个仓库的 PR 摘要应更短” | reviewed, scoped soft preference candidate | 在匹配 surface 中影响排序或改写 |
| “这个模块过去常因某类边界失败” | procedural experience candidate | 经当前 artifact 复核后影响诊断与验证计划 |
-**Reward Memory** 解决的是“有价值的人类判断怎样跨 run 复用”,不是“谁有权执行动作”。它把
+**Reward Memory** 解决的是“有价值的人类判断怎样跨 run 复用”。它把
run reward、hard policy、soft preference、procedural experience 与 working context 分开,
并要求 source、scope、authority、freshness、supersession 和 application receipt。记忆的
confidence 不会扩大权限,召回的技术经验也必须在当前代码和证据上重新验证。
diff --git a/docs/development/control-plane-course/01-agent-loop-effectful-program.md b/docs/development/control-plane-course/01-agent-loop-effectful-program.md
index e5bf112433..b0078df691 100644
--- a/docs/development/control-plane-course/01-agent-loop-effectful-program.md
+++ b/docs/development/control-plane-course/01-agent-loop-effectful-program.md
@@ -4,7 +4,7 @@
## 这一讲要建立的判断
-Harness 不是“一堆状态机”,而是 agent loop 的 effectful program 和 effect
+Harness 是 agent loop 的 effectful program 和 effect
interpreter。agent loop 是被解释的循环,harness 才是解释外部 effect 的程序;
状态机只是 harness 内部的决策表。
@@ -32,7 +32,7 @@ while true:
model -> effect request -> harness interprets effect -> observation -> model
```
-模型输出的是动作请求,不是动作本身。真正的执行、权限、预算、调度、失败恢复、
+模型输出的是动作请求。真正的执行、权限、预算、调度、失败恢复、
证据沉淀都发生在 harness 这一侧。
## 为什么 harness 是这个解释器
@@ -107,7 +107,7 @@ Agent proposes next bounded turn
传递一个可调用对象。它的 `handler` 是数据:packet 里的 `next_effect` 编码下一组
CLI 动作、scheduler ACK 和 failure hint,由 host 或下一轮 automation 执行。
-这个差异不是缺一个 middleware 层,而是控制面的合理形状:
+这个差异是控制面的合理形状:
- 可以 short-circuit:`decision` / `effective_action` 直接表达
`skip`、`wait`、`monitor_quiet_skip`、`repair_bridge`、`ask_owner`,不会假装原
@@ -139,7 +139,7 @@ ACK 和 writeback 都编码进同一个 request。模型仍然只提出 effect r
如果未来厂商 API 原生支持 serial tool calls 或 interleaved reasoning,对 LoopX
来说只是解释器内部的一种 execution mode:
-- 串行、并行、交错是 execution strategy,不是新的状态机;
+- 串行、并行、交错是 execution strategy
- `effect_request -> interpretation -> observation -> next_effect` 仍然稳定;
- `next_effect` 从一条 CLI 命令变成一段有序 effect program。
@@ -199,7 +199,7 @@ transaction 直接完成 decision、durable write 与 canonical receipt projecti
这些路径的 authority boundary 不同:quota CLI 跨 agent/host,turn driver 拥有
callback,task lease 则在自己的 native transaction 内完成原子 persistence。把它们
-塞进一个 shared executor 会隐藏 owner,而不是减少重复知识。当前共享层只统一可复用
+塞进一个 shared executor 会隐藏 owner。当前共享层只统一可复用
primitive,不统一执行权。
## 四条不变量比类名更重要
@@ -213,11 +213,11 @@ Effect Program 的价值落在四条可复核不变量上:
4. **可重放、至多一次**:已提交 prefix 可以恢复,但同一 identity 不重复结算。
普通 successor completion 仍是 Todo bounded context 的 lifecycle action,可以在
-settlement 前建立下一条 runnable frontier;它不是 terminal closeout。只有 final
+settlement 前建立下一条 runnable frontier;只有 final
`no_followup` 会改变 Goal 的终态,因此必须放到 matching spend 后。这样无需放宽
`terminal_no_followup` 守卫,也不会出现“先终止、再给终态 effect 补 spend”的例外。
-测试不是从当前输出生成 golden,而是用独立语义 oracle 检查三类 adapter:
+测试是用独立语义 oracle 检查三类 adapter:
- `test_effect_program_adapter_conformance.py` 统一验证 identity、receipt 顺序、failure、
short-circuit 和 scheduler-outside-settlement,并用 step reorder、failure 丢失、
diff --git a/docs/development/control-plane-course/02-goal-control-plane-architecture.md b/docs/development/control-plane-course/02-goal-control-plane-architecture.md
index 05405bf61b..efddc21848 100644
--- a/docs/development/control-plane-course/02-goal-control-plane-architecture.md
+++ b/docs/development/control-plane-course/02-goal-control-plane-architecture.md
@@ -25,10 +25,9 @@ prompt / transcript
```
Codex 原生 Goal 已经完成关键的第一步:`thread/goal/set` 把 objective、status 与可选预算绑定到
-thread,`thread/goal/get` 允许读回,host 可以围绕它继续 `turn/start`。LoopX 解决的不是
-“再存一遍 goal string”,而是原生 Goal 故意没有承担的项目控制状态:todo graph、claim、
+thread,`thread/goal/get` 允许读回,host 可以围绕它继续 `turn/start`。LoopX 解决的是原生 Goal 故意没有承担的项目控制状态:todo graph、claim、
scoped gate、effect receipt、跨 host cadence、领域 observation、replan 和 recovery。每轮模型
-只接收这些状态派生出的 compact interaction contract,而不是全部历史。
+只接收这些状态派生出的 compact interaction contract。
长程 Agent 的困难不只在模型推理。一次模型 turn 结束后,下面的事实仍要继续成立:
@@ -36,7 +35,7 @@ scoped gate、effect receipt、跨 host cadence、领域 observation、replan
- 外部世界变化后,Agent 能区分“继续做”“等一等”“问人”和“已经结束”;
- 多个 Agent 不会把软认领、执行占用和写权限混成同一个 owner;
- 一次成功调用不会在缺少验证和写回时被误报成进展;
-- 失败、重启、换 session 后,下一轮从已提交事实恢复,而不是重猜上一轮发生了什么。
+- 失败、重启、换 session 后,下一轮从已提交事实恢复。
LoopX 解决的是这组 **goal-level control-plane** 问题:无人干预时靠确定性合同跑稳,有人
干预时把反馈写成 scoped decision、路线修订或经验,使下一轮跑得更好。先看三个差异很大的
@@ -52,7 +51,7 @@ LoopX 解决的是这组 **goal-level control-plane** 问题:无人干预时
## 先分清四种运行责任
-LoopX 的目录、状态文件和执行角色不是同一个分类维度。读一轮真实执行时,先问四个
+读一轮真实执行时,先问四个
owner:
| 角色 | 负责什么 | 不负责什么 |
@@ -70,15 +69,13 @@ owner:
恢复:Kernel -> next todo / gate / monitor / turn -> Agent
```
-Domain State、evidence、receipt 和 projection 是这些角色交换或派生的工件,不是第五个
-owner。Extension 负责 provider 的安装、启停、升级和分发,也不是第五种运行责任;
+Domain State、evidence、receipt 和 projection 是这些角色交换或派生的工件。Extension 负责 provider 的安装、启停、升级和分发;
host/runtime 承载 session、工具和调用,也不新增领域 decision owner。
## Showcase A:PR Issue Fix
Issue-Fix 的产品承诺是:把一条公开 issue 持续推进成小而聚焦、验证充分、可审阅的 PR,
-并跟进到 merged、closed 或明确 no-follow-up。它不是“一次 prompt 生成 patch”,因为真实
-交付还包含候选判断、复现、修改、CI、review correction、冲突、通知、等待和终局收口。
+并跟进到 merged、closed 或明确 no-follow-up。
```mermaid
flowchart LR
@@ -130,14 +127,14 @@ fact,使下一轮可以重新计算 frontier:
| 外部写入结果不确定 | effect receipt + provider readback/reconcile | 先确认外部事实,再决定 retry、successor 或 closeout |
| PR merged、closed 或明确不再跟进 | terminal evidence + no-follow-up rationale | monitor 可关闭,后续 Turn 不会继续轮询已经结束的工作 |
-因此,这个 bot 的“稳定执行”不是一段永不中断的推理,也不是一个永不犯错的 Agent。它允许
+它允许
模型、session、host 和外部系统在边界处失败,但不允许丢失已经确认的事实、effect identity
和下一步恢复路径。长程稳定的目标,是让错误可发现、可归因、可恢复;即使 Agent 犯错,
已提交事实仍然有效,系统仍能形成下一步 frontier。
这也是后续课程的索引:第 3 讲解释 packet 与一次 Turn,第 5 讲解释 claim、successor 和
handoff,第 7 讲解释 monitor cadence 与 quiet wake,第 8 讲解释 evidence、reconcile 和
-self-repair。这里先记住一个判断标准:**稳定不是不中断,而是每次中断后都能从外置事实恢复。**
+self-repair。这里先记住一个判断标准:**稳定是每次中断后都能从外置事实恢复。**
### 一条交付主线,怎样反哺执行系统
@@ -182,7 +179,7 @@ flowchart LR
Capability Pack;可选或独立版本的实现进入 extension/provider;host 特有的 session、工具
和事件适配留在 host adapter。只有 LoopX 默认必须拥有的通用生命周期规则才进入 Kernel。
-因此,“系统能力自进化”不是第七个架构层,也不是模型拥有了修改自身的特权。它是同一条
+它是同一条
goal-level lifecycle 管理的一类进阶工作:交付证据发现缺口,Kernel 授权改进,独立执行面
产出候选版本,验证与发布合同决定是否激活,readback 和 guardrail 决定保留还是回滚。
@@ -244,7 +241,7 @@ issue body、raw check log、凭据或本地路径。GitHub 仍是权威来源
## Showcase B:Multi-Agent 研究团队
研究协作复用 Goal、Todo、claim、lease、证据与独立验收。角色只声明自己的研究工作与
-写入边界;创建任务或发送消息不等于启动 worker,也不授予实验、推广或发布权限。
+写入边界;
当前可运行示例见
[managed research team](../../../examples/managed-research-team/README.md),
@@ -283,8 +280,8 @@ flowchart LR
```
图中只有经过 Kernel 接受的 transition 才能改变工作生命周期。Explore Graph 上的
-`supports`、`refutes`、`depends_on` 或 `leads_to` 是证据关系,不是执行边;Explore Harness
-输出的是候选组合和风险说明,不是 claim、launch 或 spend receipt。
+`supports`、`refutes`、`depends_on` 或 `leads_to` 是证据关系;Explore Harness
+输出的是候选组合和风险说明。
### Graph 记住什么,Harness 计算什么
@@ -383,7 +380,7 @@ Domain State 保存 feasibility、PR lifecycle、experiment result、hypothesis
## Goal Control Plane Authority Map
-下面的总览图不是源码层次图。它表示事实、决策、执行和回执怎样跨边界流动。
+它表示事实、决策、执行和回执怎样跨边界流动。
```mermaid
flowchart TB
@@ -420,8 +417,7 @@ flowchart TB
读图时先记住四种运行责任,再看两个工件边界:
-1. **Kernel 拥有 goal lifecycle。** Host 被唤醒不等于获得 delivery 权限,一轮结束也不等于
- goal 完成。
+1. **Kernel 拥有 goal lifecycle。**
2. **Capability 拥有翻译规则。** 它理解 `CHANGES_REQUESTED`、experiment result 或
holdout metric,但只返回 typed proposal。
3. **Provider 拥有外部 I/O。** 它返回 bounded observation 或 readback,不决定后续 transition。
@@ -457,9 +453,6 @@ sequenceDiagram
关键不变量:
-- observation 不是 transition;
-- proposal 不是 authority;
-- result 不是 accepted result;
- accepted result 在 durable writeback 后才构成进展;
- spend 晚于验证与写回;
- scheduler proposal 在 host apply 并形成 ACK 前仍未结算。
diff --git a/docs/development/control-plane-course/03-first-real-loop.md b/docs/development/control-plane-course/03-first-real-loop.md
index 8da2be7125..e4afe7c1e8 100644
--- a/docs/development/control-plane-course/03-first-real-loop.md
+++ b/docs/development/control-plane-course/03-first-real-loop.md
@@ -64,7 +64,7 @@ read current source state
Showcase 的价值不是给出可复制的 prompt,而是证明这个 transaction shape 能在多轮之后
仍保留正确的 identity、authority、evidence 和 recovery。仓库中的
-`docs/showcases/showcase-catalog.json` 只是公开证据目录,不是隐藏的工作流模板。
+`docs/showcases/showcase-catalog.json` 只是公开证据目录。
Auto ML 还说明同一轮可以消费两个可选 read model:Explore Graph 提供与当前候选相关的
正负证据 lineage,Explore Harness 提供基于 todo、scope 和资源容量的 analysis-only
@@ -124,12 +124,10 @@ LoopX packet 则让当前 Turn 不依赖模型记住完整项目过程。Codex A
Packet 有三个明确的非目标:
- 它不是 canonical state,不能被当作长期写入源;
-- 它不是 authority,显示某项工作不代表可以越过 gate 或 workspace guard;
-- 它不是历史摘要,长 rationale 应留在 evidence artifact,只通过紧凑 ref 进入本轮。
## 一次 Codex App 交互的真实路径
-下面不是概念伪代码,而是公开 CLI 的真实调用路径。任务文本、goal id 和 agent id 都使用占位符,读者可以在自己的测试仓库中复现。
+下面是公开 CLI 的真实调用路径。任务文本、goal id 和 agent id 都使用占位符,读者可以在自己的测试仓库中复现。
### 0. 用户只表达目标
@@ -326,7 +324,7 @@ loopx quota spend-slot \
--agent-id
```
-Spend 是“这轮已形成有效控制面推进”的账,不是“模型被唤醒过”的计数器。dry-run、read-only poll、monitor quiet skip、scheduler ACK 都不应该先花配额。
+Spend 是“这轮已形成有效控制面推进”的账。dry-run、read-only poll、monitor quiet skip、scheduler ACK 都不应该先花配额。
## 为什么 App automation 不是主循环本身
@@ -506,7 +504,7 @@ return {
#### 3. Heartbeat prompt 是 host contract 编译器
-`loopx/heartbeat_prompt.py::build_heartbeat_prompt` 不是 scheduler。它把 goal、peer identity 和可用能力编译成 host 可执行的 prompt:
+它把 goal、peer identity 和可用能力编译成 host 可执行的 prompt:
```python
if not (full or compact or brief or thin):
@@ -526,7 +524,7 @@ quota_spend_command = render_quota_spend_command(...)
refresh_state_command = render_refresh_state_command(...)
```
-核心不是字符串拼接,而是身份约束:多 peer goal 缺少 `agent_id` 时直接失败。否则 claim、workspace guard、quota 和 spend 都无法归因。
+核心是身份约束:多 peer goal 缺少 `agent_id` 时直接失败。否则 claim、workspace guard、quota 和 spend 都无法归因。
#### 4. Quota 把很多局部判断收敛成一个执行决定
@@ -572,21 +570,19 @@ effective_action = _effective_action(...)
#### 读完这一段应能回答
-1. 为什么 `start-goal` 成功返回不等于已经执行 agent turn?
2. 为什么 connected 的判定不能只看 `.loopx/registry.json` 是否存在?
3. 多 peer heartbeat 为什么必须显式携带 `agent_id`?
-4. `should_run=True` 时,哪几类动作仍然不是正常 delivery?
5. 哪一层负责建议 host cadence,哪一层真正触发模型?
## 常见误解
### “LoopX 是另一个 agent runtime”
-不是。LoopX 可以向 host 提供 prompt、调度建议和状态协议,但不替 Codex App 或 CLI 执行模型 turn。
+LoopX 可以向 host 提供 prompt、调度建议和状态协议,但不替 Codex App 或 CLI 执行模型 turn。
### “Heartbeat 每次触发都必须做事”
-不是。`interaction_contract` 可以要求等待、quiet no-op、monitor poll 或 self-repair。是否执行由当前状态决定。
+`interaction_contract` 可以要求等待、quiet no-op、monitor poll 或 self-repair。是否执行由当前状态决定。
### “P0 被用户 gate 卡住,整个 goal 就停止”
@@ -594,7 +590,7 @@ effective_action = _effective_action(...)
### “Supervisor 就是主 agent”
-不是。当前 peer 模型没有 primary/side 的运行时层级。可选 supervisor 是 equal peer
+当前 peer 模型没有 primary/side 的运行时层级。可选 supervisor 是 equal peer
上的观察和 proposal overlay;第 9 讲用它演示规则设计,第 11 讲说明它与其他扩展能力
如何复用同一个 kernel。
diff --git a/docs/development/control-plane-course/04-state-substrate.md b/docs/development/control-plane-course/04-state-substrate.md
index b839530019..2fdbbeaf16 100644
--- a/docs/development/control-plane-course/04-state-substrate.md
+++ b/docs/development/control-plane-course/04-state-substrate.md
@@ -5,7 +5,6 @@
> or the selected File/SQLite authority. See the
> [retirement contract](../../reference/protocols/event-sourced-state-contract-v0.md).
-
> **本讲结论:** Canonical event/state contract 拥有长期事实;active state、status 和
> dashboard 是可重建 read model;session context 不能替代 project memory。
@@ -79,11 +78,10 @@ truth,也不成为第四个状态源。
Runnable | Claimed | Waiting on user | Monitoring | Blocked | Review | Done
```
-这些列不是新的事实源。“Waiting on user”来自 scoped user gate,“Monitoring”来自
-带 cadence 和 target key 的 monitor,“Review”可以来自领域状态与当前 acceptance,
-而不是把每个展示名称写进 Kernel lifecycle enum。
+“Waiting on user”来自 scoped user gate,“Monitoring”来自
+带 cadence 和 target key 的 monitor,“Review”可以来自领域状态与当前 acceptance。
-看板上的移动也对应结构化算子,而不是任意拖拽:
+看板上的移动也对应结构化算子:
| 操作 | 必须保持的约束 |
| --- | --- |
@@ -102,7 +100,7 @@ closure,最终 transition 仍由 Kernel 接受或拒绝。
## Goal 不是聊天线程
-LoopX 的 durable identity 是 goal,不是某个 Codex thread:
+LoopX 的 durable identity 是 goal:
```text
Goal: 长期存在的目标、边界和进度身份
@@ -130,7 +128,7 @@ Dashboard: 只读观察和路由界面
| Project memory | goal identity、objective/boundary、todo/gate、紧凑 evidence、run lineage | 被 replay、投影或由另一 peer 恢复 | 可以,但必须经过 canonical contract |
| Environment | 当前 checkout、host capability、外部服务与 fresh source | 在 handoff 之间变化 | 不能,必须重新探测 |
-恢复的目标不是逐字重建旧 transcript,而是从持久化事实和新鲜环境重新生成可执行
+恢复的目标是从持久化事实和新鲜环境重新生成可执行
决定:
```text
@@ -142,7 +140,7 @@ Project memory 的充分性标准是:更换 session 后,新的 peer 仍能
condition。它不要求逐字复现旧推理。第 5 讲会把这个要求进一步写成 handoff 的
不动点检查。
-可以把这看成长期任务的“最小可恢复状态”,而不是“最大可记忆内容”。外置状态应优先保存:
+可以把这看成长期任务的“最小可恢复状态”。外置状态应优先保存:
- 能改变合法 action set 的事实,例如 gate、claim、capability 与 workspace boundary;
- 能改变下一步判断的事实,例如 fresh observation、acceptance gap 与 monitor due time;
@@ -277,7 +275,7 @@ projection_synced
- 当前 peer lane 在做什么?
- 是否有 contract errors、projection gaps 或 repair needs?
-Status 不是写入口。Dashboard、Lark kanban、review packet 都应该消费 status 或其他 public-safe projection,而不是反向解析私有源文件再写回。
+Dashboard、Lark kanban、review packet 都应该消费 status 或其他 public-safe projection。
## Core State、Domain State 与 Runtime Artifact
@@ -330,8 +328,8 @@ os.replace(tmp_name, path)
从这段代码应读出三个边界:
-1. Domain State 是 project-local、按 goal 与 pack 分区的事实,不是全局 memory dump。
-2. 稳定 key 和 unchanged 判定用于幂等观察,不代表领域 pack 可以决定下一轮执行。
+1. Domain State 是 project-local、按 goal 与 pack 分区的事实。
+2. 稳定 key 和 unchanged 判定用于幂等观察。
3. 返回值显式使用 `path_recorded=False`,public receipt 不应泄露本地路径。
Issue-Fix 与 ML Experiment 的 smoke 分别验证这条通用 seam:
@@ -386,8 +384,7 @@ CLI validation
这里有三个不能省略的性质:
- `agent-a` 必须是注册 peer;
-- claim 是 soft ownership,不是永久权限;
-- status 看到 claim 不等于 status 自己写了 claim。
+- claim 是 soft ownership
## 为什么不能直接编辑 Projection
@@ -425,7 +422,7 @@ registry policy
= current status projection
```
-Replay 不是简单地重放聊天。聊天里可能有:
+聊天里可能有:
- 未执行的建议;
- 失败的命令;
@@ -433,7 +430,7 @@ Replay 不是简单地重放聊天。聊天里可能有:
- 私有文本;
- 被后续状态 supersede 的结论。
-事件则应明确区分 proposal、attempt、executed receipt 和 validation。例如 supervisor 的 `inject` proposal 不是 session 已被注入的证明;只有 capability-matched host receipt 才是执行事实。
+事件则应明确区分 proposal、attempt、executed receipt 和 validation。只有 capability-matched host receipt 才是执行事实。
## Projection Gap:控制面常见故障
@@ -680,7 +677,6 @@ loopx --format json quota should-run --goal-id --agent-id
### 读完这一段应能回答
-1. Registry 为什么不是 todo truth?
2. 为什么 event id 冲突必须 fail closed?
3. Markdown fallback 为什么应保留,但不能继续定义新 runtime 语义?
4. `state_projection_gap` 在哪一层产生,又在哪一层改变执行选择?
diff --git a/docs/development/control-plane-course/05-work-graph-and-peers.md b/docs/development/control-plane-course/05-work-graph-and-peers.md
index d8a66f634c..0819396456 100644
--- a/docs/development/control-plane-course/05-work-graph-and-peers.md
+++ b/docs/development/control-plane-course/05-work-graph-and-peers.md
@@ -28,7 +28,7 @@
## 从三个 Showcase 看同一类工作图
-Issue-Fix、Single-Agent Auto ML 和 Auto Research 的 todo 文本不同,但都不是线性 checklist:
+Issue-Fix、Single-Agent Auto ML 和 Auto Research 的 todo 文本不同:
```text
Issue-Fix
@@ -53,7 +53,7 @@ Auto Research
-> holdout | retry | retirement | promotion_gate
```
-图中的箭头不是模型随口建议的“下一步”,而是带 lineage 的 successor transition。三条图
+图中的箭头是带 lineage 的 successor transition。三条图
都需要回答相同问题:
| 问题 | Issue-Fix | Single-Agent Auto ML | Auto Research |
@@ -86,7 +86,7 @@ identity + role + priority + task_class + action_kind
+ evidence / completion rationale
```
-因此 todo 集合不是按顺序执行的脚本,而是当前 goal 的可计算 frontier。
+因此 todo 集合是当前 goal 的可计算 frontier。
## 两类 Owner 与五类 Task Class
@@ -111,7 +111,7 @@ identity + role + priority + task_class + action_kind
## Priority 不是隐藏工作流
-Todo 文本通常带 `[P0]`、`[P1]`、`[P2]`。Priority 影响候选排序,但不是唯一决策:
+Todo 文本通常带 `[P0]`、`[P1]`、`[P2]`。Priority 影响候选排序:
```text
priority
@@ -141,7 +141,7 @@ quota 可以同时返回:
- `agent_channel.must_attempt=true`,要求推进 P1;
- `safe_bypass_allowed=true`,说明旁路边界。
-这不是矛盾,而是双通道控制。
+这是双通道控制。
## Equal Peer Runtime
@@ -151,7 +151,7 @@ quota 可以同时返回:
- 没有永久的主执行者;
- 没有永久的辅助执行者;
- todo claim 和 continuation policy 决定当前工作归属;
-- task-scoped coordination 不授予 durable authority;
+
- 旧 hierarchy 字段只允许存在于 exactly-once migration reader。
对应实现是 `loopx/control_plane/agents/runtime_model.py`。它只暴露 `AgentRuntimeModel.PEER_V1`。
@@ -184,8 +184,7 @@ Claim 可以过期、清除、被 completion/supersede 结束。Status 会投影
## Lifecycle Authority:显式委托不等于 Leader
Equal peer 的默认规则是:一个 agent 不能修改另一个 peer 已 claim 的 todo。但
-orchestration 或 meta agent 有时确实需要完成、转交或废弃停滞工作。正确做法不是恢复
-永久 leader,而是在 goal 上声明动作级授权:
+orchestration 或 meta agent 有时确实需要完成、转交或废弃停滞工作。正确做法是在 goal 上声明动作级授权:
```yaml
coordination:
@@ -217,18 +216,18 @@ if (rejection === "claim_owner_mismatch") {
}
```
-这是同一 `authority` 决策中的片段,不是新的调用接口。canonical 事务从 registry
+这是同一 `authority` 决策中的片段。canonical 事务从 registry
读取并规范化 grant,将 facts 交给 TS owner 统一决策。Python 只保留 registry facts
与 grant 配置校验,不再暴露独立的 lifecycle mutation authorizer。
这份 grant 有四个边界:
-1. 只授予列出的 lifecycle action,不授予 repo、quota 或 user decision 权限;
+1. 只授予列出的 lifecycle action
2. actor 必须是当前 goal 的 registered agent;
3. `excluded_agents`、`bound_agent` 和精确 user-gate scope 仍独立生效;
4. reason 进入 mutation receipt,使越权操作可追溯。
-因此它表达的是一项可撤销的 goal-local capability,而不是 agent 之间的持久层级。
+因此它表达的是一项可撤销的 goal-local capability。
## Lease:显式、可选的执行占用
@@ -257,8 +256,7 @@ writeback 都必须提交当前 version。Release 会保留 inactive terminal re
实现边界可以直接由调用图证明:产品 CLI 在
`loopx/cli_commands/task_lease.py` 调用 native acquire transport,transaction owner
-是 `loopx/control_plane/work_items/task_lease_acquire.ts`,而不是 todo claim 或 quota
-pipeline。`acquire_task_lease()` 只保留 transport compatibility。生命周期与幂等合同
+是 `loopx/control_plane/work_items/task_lease_acquire.ts`。`acquire_task_lease()` 只保留 transport compatibility。生命周期与幂等合同
由 native TS tests、`tests/control_plane/test_task_lease.py` 和
`examples/control_plane/task-lease-runtime-smoke.py` 看护。
@@ -325,8 +323,7 @@ quota、gate、capability、claim/lease 和 workspace guard;packet 本身不
2. status-neutral run 不得冒充业务进展,只有真实后续 work run 才切换到
`post_handoff_run_seen`。
-连续 N 次 handoff 可以作为低频状态稳定性资格测试,但不是日常执行流程,也不
-能用“漂移分数低”替代任务的 artifact、validation 或 outcome evidence。
+连续 N 次 handoff 可以作为低频状态稳定性资格测试。
### Handoff 携带 Material Frontier,不复制材料正文
@@ -369,7 +366,7 @@ def project_material_frontier_for_handoff(frontier):
投影保留 `current`、`stale`、`missing`、`inaccessible`、`required_unread` 的计数和至多
四个稳定 material id;材料正文、原始 transcript、凭证和本机路径不进入 packet。接手者
先按 id 从 canonical source 重新读取,再判断材料是否 current。这样 handoff 传递的是
-“恢复决策面所需的引用与缺口”,不是一份越来越大的 session memory 副本。
+“恢复决策面所需的引用与缺口”。
## Capability Gate:能做不等于被授权
@@ -390,17 +387,11 @@ loopx --format json quota should-run \
--available-capability filesystem_write
```
-Capability 是 preflight 条件,不是 permission:
-
-- 有 `network` 不代表可以上传私有材料;
-- 有 `filesystem_write` 不代表可以写任意 repo;
-- 有 `session_termination` 不代表 supervisor 可以随意终止 session;
-- 有 `benchmark_runner` 不代表可以提交 leaderboard。
+Capability 是 preflight 条件:
权限仍来自 goal boundary、user gate、workspace policy 和 host authority。
-未知或非 owner-held 的缺失能力会作为 `repair_missing` 暴露给 agent,而不是
-直接跳过。Agent 必须自己判断能否满足:例如独立 worktree/branch 可以由当前
+未知或非 owner-held 的缺失能力会作为 `repair_missing` 暴露给 agent。Agent 必须自己判断能否满足:例如独立 worktree/branch 可以由当前
runtime 自证,就执行 repair 并写回 `capability_gap_status=fixed`;不能证明就写
blocker。分支/worktree 的最终约束仍由 `--task-repository`、
`--required-write-scope` 和 workspace guard 执行,不要在 capability gate 里
@@ -461,8 +452,8 @@ loopx todo update \
只有真正影响所有 peer 的 gate 才使用 `--global-gate`。不要因为不确定就扩大阻塞面。
-在 multi-agent goal 中,`blocks_agent` 和 `global_gate=true` 都缺失时,语义不是
-“默认全局阻塞”,而是“authority scope 不完整”。把不确定性扩大成全局 gate 会让一个
+在 multi-agent goal 中,`blocks_agent` 和 `global_gate=true` 都缺失时,语义是
+“authority scope 不完整”。把不确定性扩大成全局 gate 会让一个
局部决策冻结所有独立 lane,也无法从状态解释用户当时究竟授权了什么。Quota 因此把它
投影为有界修复:
@@ -572,7 +563,7 @@ loopx todo complete \
--no-follow-up
```
-`no_followup` 不是“我不想继续”。它必须与 acceptance evidence、空 frontier、已关闭 monitor/successor/replan gap 一致。`terminal_no_followup` 是 CLI 派生的 closure 状态,不是用户可以随意定义的 todo status。
+`no_followup` 必须与 acceptance evidence、空 frontier、已关闭 monitor/successor/replan gap 一致。`terminal_no_followup` 是 CLI 派生的 closure 状态。
## Supersede:改变方向而不伪造完成
@@ -594,7 +585,7 @@ loopx todo supersede \
## Review 不是特殊身份
-Review 是普通 todo 的 `action_kind=review` 和 continuation policy,不是一个隐藏的 primary reviewer 身份。
+Review 是普通 todo 的 `action_kind=review` 和 continuation policy。
例如作者完成实现后创建:
@@ -635,7 +626,7 @@ M1 monitor external PR
- M1 未到期,不消耗 branch width,也不反复唤醒;
- goal 不应进入 terminal closure。
-这里特别说明一个调度边界:即使另一个 claimed todo 被 gate,未认领的 advancement todo 仍应唤醒所有 eligible peer,而不是因为 goal 中存在 `claimed_by` 就饿死。
+这里特别说明一个调度边界:即使另一个 claimed todo 被 gate,未认领的 advancement todo 仍应唤醒所有 eligible peer。
## 实验:构造一个可计算 Frontier
@@ -696,7 +687,7 @@ loopx --format json quota should-run \
## 核心代码领读:一个 todo 怎样成为某个 peer 的合法工作
-这一讲的主线不是“找到最高优先级 todo”,而是逐层缩小候选集合:
+这一讲的主线是逐层缩小候选集合:
```text
todo contract
@@ -729,8 +720,6 @@ class TodoContinuationPolicy(str, Enum):
SAME_AGENT_NON_DELIVERY = "same_agent_non_delivery"
```
-因此 `open` 不等于“可执行”:一个 open `continuous_monitor` 可能尚未 due,一个 open `user_gate` 等待的是用户,一个 open `advancement_task` 还可能被 capability 或 workspace 卡住。
-
再看 `loopx/control_plane/todos/completion_policy.ts` 中 continuation 的默认值。
私有 `continuationPolicy` 在 `resolveTodoCompletionPolicy` 整项完成策略内使用:
@@ -783,7 +772,7 @@ def select_peer_for_work(registered_agents, *, work_key):
return agents[int.from_bytes(digest[:8], "big") % len(agents)]
```
-这是 deterministic routing helper,不是 durable ownership。真正 ownership 仍要经过 todo claim/lease 写回。
+这是 deterministic routing helper。真正 ownership 仍要经过 todo claim/lease 写回。
### 3. Capability gate 输出候选集,不替 agent 领取 todo
@@ -860,7 +849,7 @@ if current_workspace:
}
```
-这里不是代码风格 gate,而是 attribution gate:后续 refresh 与 quota spend 要能证明交付发生在 todo 声明的 repository、正确的 peer workspace 中。
+这里是 attribution gate:后续 refresh 与 quota spend 要能证明交付发生在 todo 声明的 repository、正确的 peer workspace 中。
### 断点练习
@@ -872,9 +861,8 @@ if current_workspace:
### 读完这一段应能回答
1. 为什么 `task_class` 不能由 `status` 推断?
-2. `select_peer_for_work` 为什么不是 claim?
3. migration reader 与 live runtime model 的边界在哪里?
-4. capability gate 为什么返回 candidate set,而不是唯一 todo?
+4. capability gate 为什么返回 candidate set?
5. worktree guard 与 spend causality 有什么关系?
6. delegated lifecycle authority 为什么没有把 peer 变成永久 leader?
7. material handoff 为什么只传引用、状态计数和截断标记?
@@ -909,7 +897,7 @@ if current_workspace:
1. Claim 和 lease 的差别是什么?
2. Required capability 为什么不是权限?
3. 什么情况下 user gate 应是 global?
-4. 为什么 review 应建模成普通 todo,而不是固定执行者的特权?
+4. 为什么 review 应建模成普通 todo?
5. Completion 缺少 successor 和 no-followup 时,系统为什么不能终止?
下一讲把这个工作图交给决策内核,逐层拆解 `quota should-run` 如何编译出本轮 interaction contract。
diff --git a/docs/development/control-plane-course/06-quota-decision-kernel.md b/docs/development/control-plane-course/06-quota-decision-kernel.md
index 53539ed2cd..2f9d403d1b 100644
--- a/docs/development/control-plane-course/06-quota-decision-kernel.md
+++ b/docs/development/control-plane-course/06-quota-decision-kernel.md
@@ -39,7 +39,7 @@
`build_quota_should_run` 的工作就是把这些 source facts 按稳定 precedence 编译成
interaction contract。后面的字段、mode 和 scheduler hint 都应能回到这张表中的某个
-判断,而不是各自发明一套“是否继续”。
+判断。
## 为什么叫 Quota,却不只是配额
@@ -233,7 +233,7 @@ agent identity matches this quota call?
- user-owned actions;
- execution profile。
-这一步先于 todo 选择,因为 todo runnable 不代表越过 goal boundary 后仍合法。
+这一步先于 todo 选择。
### 3. Normalize user gates
@@ -260,8 +260,6 @@ Repair 必须改变 machine-visible frontier,例如:
- active state next action;
- agent vision patch。
-只写“已重新思考”不是 repair delta。
-
### 5. Apply capability gate
从 open advancement todos 中筛出本轮能力可满足的候选。
@@ -295,7 +293,7 @@ Repair 必须改变 machine-visible frontier,例如:
### 9. Compose scheduler hint
-调度不是另一个独立 AI 判断。它从已解析的 interaction contract 和 lifecycle state 派生 cadence class、RRULE 建议、ACK 和 spend policy。
+它从已解析的 interaction contract 和 lifecycle state 派生 cadence class、RRULE 建议、ACK 和 spend policy。
## 决策优先级为什么重要
@@ -336,7 +334,7 @@ D1 user gate open
P1 independent and runnable
```
-结果:user channel 通知 D1;agent channel 执行 P1;不是全局 wait。
+结果:user channel 通知 D1;agent channel 执行 P1;
### Case C:只有未到期 monitor
@@ -377,7 +375,7 @@ evidence creates scoped gate G1 and blocked successor T1
periodic autonomous replan obligation = due
```
-这不是“monitor 已完成,所以 quiet”的状态。合理推导是:
+合理推导是:
1. monitor 的一次 poll 结束,并以 compact evidence 写回;
2. G1 进入 user channel,T1 在对应 decision scope 上保持不可交付;
@@ -385,7 +383,7 @@ periodic autonomous replan obligation = due
4. 只有不依赖 G1、且 interaction contract 明确允许的 repair 或独立工作才可进入 agent channel;
5. host 依据新 contract 重算 cadence,不能沿用 M1 的旧 monitor backoff。
-这里的复杂性不是三个 feature 相加,而是一次 evidence transition 同时改变 gate、frontier 和 scheduler identity。
+这里的复杂性是一次 evidence transition 同时改变 gate、frontier 和 scheduler identity。
### Case G:`user_action` 看起来相关,但不能满足 decision scope
@@ -421,8 +419,7 @@ short_pool active usage = 1
T1/T2 resume_when = capacity_available:short_pool
```
-结果:Harness packet 可以帮助解释当前 portfolio,但 quota frontier 仍为空;本轮应 wait,
-而不是 claim、launch 或 spend。已有 external task 的 monitor 也不因为 planner 产生新排名
+结果:Harness packet 可以帮助解释当前 portfolio,但 quota frontier 仍为空;本轮应 wait。已有 external task 的 monitor 也不因为 planner 产生新排名
就提前 poll。资源 readback 释放槽位后,Kernel 重新计算 `resume_when`,只暴露合法候选。
如果 Harness 从 Graph 读到一条新 `refutes` edge,也只能形成 retirement/replan proposal。
@@ -446,11 +443,11 @@ else:
具体 user todo 未投影,需修复 LoopX 状态投影
```
-这是状态契约错误,不是文案问题。
+这是状态契约错误。
## Spend 规则
-Quota slot 表示一次有效推进,不是一次调用。
+Quota slot 表示一次有效推进。
### 应 spend
@@ -606,7 +603,7 @@ should_run = bool(
effective_action = _effective_action(...)
```
-workspace guard 在这里覆盖 capability/self-repair,是因为任何会写 repository 的修复也不能发生在错误 workspace。课堂上可把这些 flag 画成 priority lattice,而不是互斥 enum。
+workspace guard 在这里覆盖 capability/self-repair,是因为任何会写 repository 的修复也不能发生在错误 workspace。课堂上可把这些 flag 画成 priority lattice。
### 4. `terminal_no_followup` 必须由完整 closure 推导
@@ -664,7 +661,7 @@ return (
### 5. Interaction contract 把 decision 分给三个 actor
-quota 末尾不是直接打印一句话,而是调用 `build_interaction_contract`,形成:
+quota 末尾是调用 `build_interaction_contract`,形成:
```text
user_channel -> 是否真的需要用户动作、具体问题是什么
@@ -691,7 +688,6 @@ cli_channel -> 下一条 CLI 写回、何时允许 spend
2. 为什么 projection repair 要覆盖正常 delivery?
3. workspace repair 为什么比 capability repair 更晚覆盖?
4. terminal closure 同时检查哪些 todo、monitor、successor、replan 与 acceptance 状态?
-5. `action_required=false` 为什么不代表 agent 可以 quiet no-op?
## 代码阅读方法
diff --git a/docs/development/control-plane-course/07-host-scheduler-and-heartbeat.md b/docs/development/control-plane-course/07-host-scheduler-and-heartbeat.md
index ae8c0f90b7..2ce41370a9 100644
--- a/docs/development/control-plane-course/07-host-scheduler-and-heartbeat.md
+++ b/docs/development/control-plane-course/07-host-scheduler-and-heartbeat.md
@@ -208,21 +208,19 @@ host update applied
CLI acknowledged exact applied state
```
-Scheduler ACK 本身不构成 delivery,不 spend。
-
### 兼容投影不能改变状态权威 / Compatibility preserves state authority
-`app_automation` 与 `codex_app` 是同一 proposal 的宿主投影,不是两个 scheduler
-writer。读取优先采用 common state;仅有旧 Codex state 时,保留它经 TS 验证的
-`state_key`。两份投影的 backoff、host facts 与 ACK/failure 命令都必须携带同一个键。
-否则 common state 的当前 identity/index 会被误写到旧键,触发真实的初始档位冲突;
-即使 CAS digest 相等也不代表 proposal 的状态归属正确。
+新决策统一使用 `app_automation` 携带调度建议和宿主行动。旧捕获仍可读取其中的
+`codex_app`。读取优先采用 common state。仅有旧 Codex state 时,保留 TS 验证过的
+`state_key`,并将同一个键贯穿 backoff、host facts 与 ACK/failure 命令。
+写回前须校验状态归属及 CAS 摘要,否则可能把已推进的档位写入错误的状态键。
-`app_automation` and `codex_app` project one proposal, not two scheduler writers.
-Reads prefer common state; a legacy-only Codex installation retains its
-TS-validated legacy key. Both projections must carry that same key through
-backoff, host facts and ACK/failure commands. Equal CAS digests do not prove that
-a proposal belongs to the chosen state scope.
+New decisions use `app_automation` for the cadence proposal and Host actions.
+Saved captures can still carry `codex_app`. Reads prefer common state. A
+legacy-only Codex installation retains the TS-validated state key through
+backoff, Host facts, and ACK/failure commands. Before writing, validate the
+state scope and CAS digest to keep the recorded progression in its original
+state.
兼容 Python API 与手工 Codex CLI 未显式传 `state_key` 时,从当前 packet 取得实际键;
显式键仍须匹配,不得静默改写。Trae 仍只接受 common key。这不是隐式迁移:不能把
@@ -244,7 +242,7 @@ O: host 更新 automation,并 readback observed RRULE
R: LoopX 持久化 ACK,证明 O 对应 P
```
-`O.target_matches=true` 只说明宿主当前值正确,不等于 `R.persisted=true`。如果 adapter
+`O.target_matches=true` 只说明宿主当前值正确。如果 adapter
先更新 RRULE,再重新计算一份已经显示 settled 的 hint,原 proposal 的 ACK obligation
可能被跳过。完整资格测试必须保留 P 的 `state_key`、`reset_token`、
`identity_signature` 和 target RRULE,按以下顺序验证:
@@ -359,15 +357,15 @@ Host 只有在 CLI 派生 `terminal_no_followup` 时才应自动停止。它至
open todo count == 0
```
-只是必要条件之一,不是充分条件。
+只是必要条件之一。
-`terminal_no_followup` 是 LoopX 自己派生的 runtime closure,不是用户自定义 status,也不应由 host 根据自然语言猜测。
+`terminal_no_followup` 是 LoopX 自己派生的 runtime closure。
## 原生 Codex Goal 与 LoopX Host Surface
### 原生 Goal 的持久边界
-Codex 原生 Goal 不是“在 prompt 前写 `/goal`”的文本约定。自动化 surface 通过
+自动化 surface 通过
`thread/goal/set` 把 objective、status 与可选 token budget 绑定到 thread,通过
`thread/goal/get` 读回,再用 `turn/start` 继续执行。只有普通 prompt 的 slash 前缀、
外部 polling loop 或 `codex exec` 成功,都不能单独证明 native Goal 已激活。
@@ -554,7 +552,7 @@ write 和兼容旧合同的 JSON/Markdown projection。持续运行的路径没
caller 与 unbound manual command 保留兼容入口。
端到端测试仍需把 apply 前生成的 hint 原样带过 host effect。若 effect 后重新读取一份
-hint,测试仍可能漏掉 ACK obligation 丢失。ACK 不构成 delivery,也不会 spend。缺少
+hint,测试仍可能漏掉 ACK obligation 丢失。缺少
durable ACK 时,下一轮不能把 proposal 或碰巧相同的 host 值当成已结算状态。
### 4. Monitor writeback 用 result hash 区分观察与推进
@@ -623,9 +621,9 @@ return record_quota_monitor_poll_for_decision(
)
```
-Execution context 不是渲染选项,而是 decision input。若 CLI 入口识别出 Codex App,
+Execution context 是 decision input。若 CLI 入口识别出 Codex App,
但 wrapper 只把 context 传给 `before`,`after` 会误以为自己处在未知 host,返回
-`repair_scheduler_execution_context`。这不是 monitor 产生了新阻塞,而是调用链丢失
+`repair_scheduler_execution_context`。这是调用链丢失
了 authority context。
对应回归应同时证明:
@@ -660,7 +658,6 @@ App tick
### 读完这一段应能回答
-1. 为什么 scheduler hint 不能证明 RRULE 已应用?
2. 为什么 ACK 不消耗 delivery slot?
3. 哪些字段变化应 reset stateful backoff?
4. unchanged monitor 为什么必须写 `next_due_at`?
@@ -705,7 +702,7 @@ App tick
### 把 launcher 称为 supervisor agent
-Auto Research 的 tmux launcher 只是 host launcher,不是拥有 todo 决策权的 leader agent。可选 peer supervisor 是另一套 proposal-only overlay。
+Auto Research 的 tmux launcher 只是 host launcher。可选 peer supervisor 是另一套 proposal-only overlay。
## 课后检查
diff --git a/docs/development/control-plane-course/08-evidence-refresh-and-self-repair.md b/docs/development/control-plane-course/08-evidence-refresh-and-self-repair.md
index 862f8eb449..73ebfca227 100644
--- a/docs/development/control-plane-course/08-evidence-refresh-and-self-repair.md
+++ b/docs/development/control-plane-course/08-evidence-refresh-and-self-repair.md
@@ -15,7 +15,7 @@
1. 区分 artifact、validation、writeback、refresh、spend 五个步骤。
2. 使用 authoritative evidence 判断 acceptance,而不是依赖 todo status。
3. 解释 projection gap、outcome floor、vision checkpoint 和 repair delta。
-4. 在连续 no-progress 时执行 self-repair,而不是降低 gate。
+4. 在连续 no-progress 时执行 self-repair。
5. 为 public/private evidence 设计安全边界和 compact lineage。
## 本讲技术契约
@@ -194,7 +194,7 @@ loopx refresh-state \
--vision-unchanged-reason "课程目标和验收标准未改变,本轮完成讲义内容交付"
```
-Refresh 不是“刷新页面”,而是一次有语义的状态 transaction:
+Refresh 是一次有语义的状态 transaction:
- 写 run classification;
- 标记 delivery scale/outcome;
@@ -229,8 +229,7 @@ Outcome floor 防止 agent 用大量微小动作伪装长期推进。连续 surf
## Agent Vision 与 Acceptance Gap
多 agent goal 中,每个 peer 有自己的 bounded vision。对同时承担 advancement 与
-continuous monitor 的长生命周期 lane,vision 不是可有可无的说明文字,而是恢复和
-replan 的基线。Agent profile 会默认把这类 lane 标成 required:
+continuous monitor 的长生命周期 lane。Agent profile 会默认把这类 lane 标成 required:
```python
def _vision_requirement(value, *, task_classes):
@@ -260,7 +259,7 @@ last patch
todo delta
```
-它不是另一份大计划,而是回答:
+它是回答:
- 这个 peer 在长期目标中负责什么?
- 什么证据说明它的 lane 可以关闭?
@@ -285,7 +284,6 @@ Vision
这条链解释了为什么 Vision 应相对稳定,却不能永久冻结:用户方向变化、验收标准
被证伪、长期 frontier 耗尽或持续局部最优时,需要一个有明确 delta 的 patch。
-反过来,新增一个 todo 不等于 Vision 已变化。
`loopx/control_plane/goals/goal_vision.py::normalize_goal_vision_packet`
把这种边界编码成 compact、public-safe、agent-scoped packet:
@@ -341,11 +339,9 @@ signal
-> explicit priority, gate, or vision writeback
```
-这是管理面整理 signal 的分析顺序,不是 LoopX 中另一套独立状态机。持久化和执行
+这是管理面整理 signal 的分析顺序。持久化和执行
权限仍由现有 Core State 合同负责:
-- 外部消息到达不等于用户已授权执行;
-- 被认为“有价值”的 signal 不等于已进入 runnable frontier;
- raw feedback 不直接覆盖 Vision,必须形成明确 source、scope 和 delta;
- performance review 可以影响下一轮优先级,但仍要通过 todo/gate/vision API 写回。
@@ -455,7 +451,7 @@ classification 或 caller 自报 repair kind 都不能关闭新 obligation。
## 两轮无推进后的 Self-Repair
-规则不是“第二轮就随便换方向”,而是系统性审计:
+规则是系统性审计:
```text
1. 重新读 exact quota interaction_contract
@@ -511,7 +507,7 @@ closeout_allowed_without_evidence = false
"9 讲课程目标、受众与验收未改变;本轮完成全部讲义并以当前 CLI/smoke 交叉验证"
```
-这条回放说明 vision checkpoint 是长期 acceptance 的闭环,不是形式化打勾。
+这条回放说明 vision checkpoint 是长期 acceptance 的闭环。
## 多 Monitor 交错时的停滞证据
@@ -533,8 +529,7 @@ material change on M2 -> reset M2 only
Quota 从 `monitor_open_items` 读取每条 lane 的 durable counter。任一 lane 达到阈值且
没有 same-agent runnable advancement 时,`monitor_no_change_streak` 形成 replan 证据;
-replan 应选择 watch expiry、明确 blocker、supersede monitor 或创建 runnable successor,
-而不是再做一次 quiet poll。若存在 same-agent runnable advancement,advancement 优先,
+replan 应选择 watch expiry、明确 blocker、supersede monitor 或创建 runnable successor。若存在 same-agent runnable advancement,advancement 优先,
但 blocked advancement 不能冒充可执行工作来压掉 replan。
这个例子同时说明了三件事:evidence 必须归属稳定 identity;聚合 read model 不能覆盖
@@ -656,8 +651,7 @@ loopx todo add \
`run_loopx_turn_once` 会把 plan、host result、task validation、writeback、spend 和 scheduler
状态写入 `runtime_root/goals//turns/.json`。这份 journal 的 owner 是
-**单个 Turn 的阶段进度**,不是 goal truth:只有 `writeback` callback 成功,长期状态才发生
-变化;只有 source state readback 才能证明 todo、vision 或 evidence 已提交。
+**单个 Turn 的阶段进度**只有 source state readback 才能证明 todo、vision 或 evidence 已提交。
这一区分让恢复可以按失败阶段精确继续:
@@ -715,7 +709,7 @@ if not delta["accepted"]:
print(delta["reason"])
```
-仅刷新 evidence ID 不构成新语义维度;旧 blocker 不因更换 work item 而成为新结果。
+旧 blocker 不因更换 work item 而成为新结果。
若 context 已截断 coverage,必须提供完整历史,缺失时资格入口拒绝写回。
成功 receipt 必须携带当前 `obligation_id`,且 outcome 属于该 obligation 的
@@ -781,7 +775,7 @@ if normalized_progress_scope == "agent_lane":
### 4. Projection gap 把 prose 漂移升级成 repair
-`loopx/control_plane/quota/projection_repair.py::build_state_projection_gap_repair_hint` 的输入来自第 4 讲的 status projection。当 active prose 看起来可执行、结构化 agent todo 却为零时,它返回 self-repair hint,而不是让 quota 安静等待。
+`loopx/control_plane/quota/projection_repair.py::build_state_projection_gap_repair_hint` 的输入来自第 4 讲的 status projection。当 active prose 看起来可执行、结构化 agent todo 却为零时,它返回 self-repair hint。
领读时追这条反向路径:
@@ -875,7 +869,6 @@ CLI/status/quota 并补 smoke;只更新文档不会改变机器的下一次决
## 课后检查
-1. Todo done 为什么不是 acceptance evidence?
2. Refresh 和 spend 分别证明什么?
3. Vision unchanged reason 什么时候是诚实的?
4. Repair delta 必须改变哪些 machine-visible 对象?
diff --git a/docs/development/control-plane-course/09-engineering-a-control-plane-rule.md b/docs/development/control-plane-course/09-engineering-a-control-plane-rule.md
index 036a3d299d..cd5a9f8b65 100644
--- a/docs/development/control-plane-course/09-engineering-a-control-plane-rule.md
+++ b/docs/development/control-plane-course/09-engineering-a-control-plane-rule.md
@@ -67,7 +67,7 @@ control_plane/todos
control_plane/work_items
```
-归属原则不是“哪个文件短”,而是 change reason:
+归属原则是 change reason:
- agent identity/supervisor observation 属于 `agents`;
- todo lifecycle 属于 `todos`;
@@ -75,7 +75,7 @@ control_plane/work_items
- cadence/ACK 属于 `scheduler`;
- repo/write-scope 选择属于 workspace/work item boundary。
-大文件是 warning signal,不是自动拆分理由。先找一组已经有 parity fixture 的 cohesive rules,再移动到 bounded context。
+大文件是 warning signal。先找一组已经有 parity fixture 的 cohesive rules,再移动到 bounded context。
## 新规则的 8 个层次
@@ -167,7 +167,7 @@ terminal_no_followup =>
普通 Python smoke 可以检查有限案例;property-based test 可以搜索更多组合;TLA+/Alloy 可以检查状态机;Lean 可以把状态、transition 和 theorem 写进依赖类型系统,并由 kernel 检查 proof term。
-Lean 的价值不是“让 agent 写更多形式化文本”,而是对少量高价值 invariants 给出机器证明,例如:
+Lean 的价值是对少量高价值 invariants 给出机器证明,例如:
- 执行过的 supervisor action 必然有 capability-matched receipt;
- terminal state 不可能同时有 runnable successor;
@@ -253,7 +253,7 @@ def select_goal_frontier_replan_rule(facts):
4. quality surface catalog 将它标为 high risk,要求 unit、smoke、canary 和 release gate;
模型行为层记为 `not_applicable`,因为确定性 precedence 不应交给模型裁判。
-这个案例的评审重点不是“新模块是否更漂亮”,而是:facts 是否来自同一 canonical
+这个案例的评审重点是:facts 是否来自同一 canonical
projection、rule order 是否完整、每条负向规则是否有反例、runtime payload builder 是否
仍复用原实现。只有这四点成立,代码移动才是行为保持的重构。
@@ -377,7 +377,6 @@ Supervisor contract 推荐把 supervisor task 作为 synthesis channel,因为
- 所有改变 authority 的决定仍写成 LoopX user todo/gate;
- supervisor 不能 claim 其他 peer 的 todo;
- supervisor 不能花其他 peer 的 quota;
-- supervisor 不是隐藏 review owner。
### Inject 为什么先有 canary
@@ -409,7 +408,7 @@ Fork 与 handoff 不同:
| handoff | 通常完成或 yield | 转移 continuation,不默认增加 branch 数 |
| fork | 继续 | 新增临时 execution branch,需要 capacity reservation |
-正确未来模型不是复制长期 peer identity,而是:
+正确未来模型是:
```text
source_agent_id
@@ -475,7 +474,7 @@ Smoke 应同时证明:
本讲只保留规则开发的入口;完整分层、频率、模型行为门和发布门见[第 10 讲](10-autonomous-agent-quality-gates.md)。
-测试先回答“这个状态和规则合理吗”,再验证实现是否符合。共享 quota/status/todo 行为可以先加 parity fixture 描述现状,但 fixture 不是授权书;如果现状与 independently reviewed invariant 冲突,应修规则并增加负向或 mutation coverage,不能刷新 golden 把错误合法化。
+测试先回答“这个状态和规则合理吗”,再验证实现是否符合。共享 quota/status/todo 行为可以先加 parity fixture 描述现状;如果现状与 independently reviewed invariant 冲突,应修规则并增加负向或 mutation coverage,不能刷新 golden 把错误合法化。
例如 gate lifecycle 至少要先写出这张语义表,再决定 schema 和 transition:
@@ -552,7 +551,7 @@ HOST_CAPABILITIES_BY_DECISION = {
}
```
-`normalize_peer_supervisor` 的关键不是 enum,而是身份约束:
+`normalize_peer_supervisor` 的关键是身份约束:
```python
if raw in (None, {}) or raw.get("enabled") is False:
@@ -572,11 +571,11 @@ return {
}
```
-`supervisor` 是某个已注册 peer 的额外职责,不是新的 primary/side hierarchy。默认空配置直接返回 `None`,所以实验功能不会默认开启。
+`supervisor` 是某个已注册 peer 的额外职责。默认空配置直接返回 `None`,所以实验功能不会默认开启。
### 2. Contract 明确 user channel 与 authority 边界
-`build_peer_supervisor_contract` 里最重要的字段不是 prompt 文案,而是权力模型:
+`build_peer_supervisor_contract` 里最重要的字段是权力模型:
```python
{
diff --git a/docs/development/control-plane-course/10-autonomous-agent-quality-gates.md b/docs/development/control-plane-course/10-autonomous-agent-quality-gates.md
index 6a900007fe..c636d5f34e 100644
--- a/docs/development/control-plane-course/10-autonomous-agent-quality-gates.md
+++ b/docs/development/control-plane-course/10-autonomous-agent-quality-gates.md
@@ -12,7 +12,7 @@
完成本讲后,开发者应该能够:
-1. 先判断状态和规则是否合理,再判断实现是否符合,而不是把当前输出录成 golden。
+1. 先判断状态和规则是否合理,再判断实现是否符合。
2. 按改动风险选择 unit、focused smoke、decision replay、canary、模型行为验证和 release gate。
3. 区分 blocking failure、advisory signal、deferred gap、`not_applicable` 和 manual hold。
4. 解释为什么常规模型行为测试是 actual-default one-arm,而双臂只服务于明确的差分或提升声明。
@@ -26,7 +26,7 @@ agent-facing packet 读案例四;文档与社区资源读案例五;release/b
## 本讲沿三个 Showcase 验证什么
-质量门禁不是脱离产品路径的测试清单。三个 Showcase 各自暴露了不同风险:
+三个 Showcase 各自暴露了不同风险:
| Showcase surface | 独立 oracle | 最小确定性证明 | 更高层证明 |
| --- | --- | --- | --- |
@@ -78,7 +78,7 @@ Explore Graph 只能消费第二组 oracle 已接受的 finding;Explore Harnes
## 第一道门:独立语义 Oracle
-写测试前先用产品规则表达期望,而不是从实现输出复制期望:
+写测试前先用产品规则表达期望:
```text
source facts
@@ -90,8 +90,7 @@ source facts
例如 `required_decision_scopes=["publish"]` 的 agent todo 遇到一个
`blocking=false` 的 `user_action`:即使提醒文本里提到 publish,它也不能授予 publish
-权限。这里的 oracle 来自 authority invariant,而不是当前 reducer 是否恰好返回
-`should_run=true`。
+权限。这里的 oracle 来自 authority invariant。
Oracle 至少要写清:
@@ -157,7 +156,7 @@ if meaningful:
- 模型通过不能覆盖 deterministic contract failure;
- full-public 全通过不能替代一个明确命名旧故障的 focused regression;
-- output 字符数没增长不能证明 agent 仍知道下一步做什么;
+
- release receipt 齐全不能替 owner 自动做发布决定。
## Quality Surface Catalog:先审计覆盖设计
@@ -179,9 +178,9 @@ loopx canary quality-audit
- `not_applicable`:这层测试不适合该语义,例如用模型判断确定性的 scheduler 优先级;
- `deferred`:这层有价值但尚未建设,必须保留 owner 和可见缺口;
-- `covered`:有真实路径和稳定 oracle,不是只写了一句“已有测试”。
+- `covered`:有真实路径和稳定 oracle。
-Catalog 不是测试结果汇总,而是“为什么这些层足够”的机器可审计设计。
+Catalog 是“为什么这些层足够”的机器可审计设计。
## PR 快速门:让普通迭代保持便宜
@@ -208,8 +207,7 @@ loopx canary premerge --from-git-diff
loopx canary smoke-suite --suite full-public --jobs 4 --timeout-seconds 120
```
-它适合主干、每日或手动运行,不应成为每个文档 patch 的同步阻塞项。保护质量不等于
-把最宽的测试频率提高到每次保存文件。
+它适合主干、每日或手动运行,不应成为每个文档 patch 的同步阻塞项。
## 真实模型门:常规 one-arm,必要时才 pair
@@ -254,16 +252,17 @@ runner。
## Agent-facing 热路径与诊断冷路径
默认 guided projection 是 agent 每轮都会消费的热路径;完整诊断包是显式请求的冷路径。
-把字段从热路径移到冷路径不是简单删 JSON,至少要同时证明:
+
+把字段从热路径移到冷路径,至少要同时证明:
1. 热路径仍保留当前 authority、selected todo、可执行 commands 和 host activation;
2. 被省略细节有显式 drill-down 命令;
3. action signature 与状态语义没有漂移;
-4. CLI budget 显示输出确实收敛,而不是把重复文本搬到另一处;
+4. CLI budget 显示输出确实收敛
5. actual-default model portfolio 中的真实 agent 行为仍正确。
冷路径不会天然降低接入效果。真正的风险是把 agent 作决定所需的信息也当成“诊断噪声”
-一起移走。因此 owner review 应逐项解释字段为什么可移除,而不是只展示字符数下降。
+一起移走。因此 owner review 应逐项解释字段为什么可移除。
## 门禁结果也是状态机
@@ -329,9 +328,8 @@ if replan_decision_allowed:
阅读断点:
-1. `monitor_quiet_skip` 只是候选结果,不是函数提前返回;
-2. `replan_decision_allowed` 显式改写 `should_run` 与 `effective_action`,所以 replan
- precedence 不是靠 prompt 文案实现;
+1. `monitor_quiet_skip` 只是候选结果
+2. `replan_decision_allowed` 显式改写 `should_run` 与 `effective_action`
3. 继续读同函数末尾的 `build_interaction_contract(payload)` 和 `_scheduler_hint(...)`:
二者都消费已经仲裁完成的 payload,host 不应重新从低层 flags 猜一次决策。
@@ -347,7 +345,7 @@ if replan_decision_allowed:
4. metamorphic case 把 advancement 改成 same-agent runnable,最终必须回到
`normal_run`,证明 replan 没有抢占真实可执行工作。
-这里测试的不是一份当前 JSON,而是两条独立 invariant:monitor 停滞按 target identity
+这里测试的是两条独立 invariant:monitor 停滞按 target identity
累计;runnable advancement 在工作选择上优先于 monitor-derived replan。
仓库用 [issue #2272](https://github.com/huangruiteng/loopx/issues/2272) 记录过对应回归:
M1、M2 交错 poll 时,错误的全局计数会让某条 lane 永远达不到 replan 阈值。下文的
@@ -426,8 +424,7 @@ if (conflicting.length) {
if (compatible.length) continue;
```
-只有 task class、scope、owner 和精确目标一致的 gate 才满足依赖;依赖一致不等于
-批准或 lease。随后 `matchingActions` 只用于错误归因
+只有 task class、scope、owner 和精确目标一致的 gate 才满足依赖;随后 `matchingActions` 只用于错误归因
`non_blocking_user_action_scope_collision`,不能成为 authority。只有不兼容 gate 时
归因 `required_decision_scope_gate_owner_mismatch`;没有匹配来源时归因
`dangling_required_decision_scope`。standing authority 的冲突与拒绝/取消后的阻塞要求
@@ -535,12 +532,11 @@ if any(_path_matches(path, BENCHMARK_SENSITIVE_TOKENS) for path in files):
再进入 `build_premerge_validation_gate`,观察 classification 如何分别生成 direct checks、
catalog run、risk-profile run 和 boundary scan。Docs-only 命中自己的 profile;只有实际
-路径命中 benchmark-sensitive token 才产生 manual hold。门禁由 diff surface 决定,
-不是由 PR 作者在描述里自报“低风险”。
+路径命中 benchmark-sensitive token 才产生 manual hold。门禁由 diff surface 决定。
## 组合案例六:Release 精确 Commit
-发布前的关键不是“这些测试最近跑过”,而是“这些回执是否属于即将打 tag 的同一个
+发布前的关键是“这些回执是否属于即将打 tag 的同一个
clean source identity”。Exact-commit gate 聚合既有通道,不另造一套 runner:
```bash
@@ -634,7 +630,7 @@ def test_goal_frontier_replan_decision_table(...):
第二层是 metamorphic test:不改变当前 agent 的 source facts,只扩大其他 peer 的 backlog,
结果必须不变;再加入当前 agent 自己的 runnable advancement,结果必须翻转。它检查的是
-agent-scope invariant,不是某份固定 JSON。
+agent-scope invariant。
第三层让 focused smoke 经由 `build_quota_should_run` 验证最终路由,防止纯 selector 正确、
integration 却漏传 facts。第四层把 surface 登记进 quality catalog 和 risk-based canary。
@@ -754,5 +750,4 @@ outcome baseline 可以消费 readiness receipt,但不能反过来用一个分
7. 哪些改动允许 agent 自合并,哪些必须留下 manual hold?
下一讲进入扩展层:Explore Graph/Harness、Single-Agent Auto ML、multi-agent kernel、
-Auto Research、supervisor 和 connectors 如何复用同一套状态内核与质量门禁,而不是创建
-第二套控制面。
+Auto Research、supervisor 和 connectors 如何复用同一套状态内核与质量门禁。
diff --git a/docs/development/control-plane-course/11-extension-layer.md b/docs/development/control-plane-course/11-extension-layer.md
index 5e7333f909..207ffb9c64 100644
--- a/docs/development/control-plane-course/11-extension-layer.md
+++ b/docs/development/control-plane-course/11-extension-layer.md
@@ -72,7 +72,7 @@ registry -> status -> quota -> interaction contract -> todo/evidence -> refresh/
## 运行责任与扩展交付
-Extension 是安装、启停、升级和分发边界,不是运行时的第五个 owner。运行时仍按四种责任
+Extension 是安装、启停、升级和分发边界。运行时仍按四种责任
分工:
| 角色 | Owns | Must not own |
@@ -137,7 +137,7 @@ State 只保存可重放的 compact facts;外部 sink 只消费 public-safe pr
## Governed External Execution:把外部副作用变成可恢复事务
-外部 capability 最危险的时刻,不是 API 明确返回失败,而是调用方不知道它到底有没有成功:
+外部 capability 最危险的时刻:
```text
provider 已经创建任务
@@ -148,8 +148,7 @@ provider 已经创建任务
```
`capability invoke` 可以直接执行 read-only operation,因为它不会产生需要结算的物质效果。
-`external_write` 则必须进入 governed external execution。它不是给 provider 套一层普通 retry,
-而是把一次外部写入拆成两段可重放事务:
+`external_write` 则必须进入 governed external execution。
```text
Goal-bound capability + exact provider revision
@@ -176,7 +175,7 @@ Goal-bound capability + exact provider revision
### Goal capability 与 material Turn 分别回答什么
-Goal enablement 与 Turn admission 不是二选一,而是两层不同粒度的授权:
+Goal enablement 与 Turn admission 是两层不同粒度的授权:
| 层 | 回答的问题 | 不代表什么 |
| --- | --- | --- |
@@ -272,18 +271,18 @@ Independent evidence refresh
-> only then promote “resumable multimodal context works” from hypothesis to evidence
```
-这里“同一 Session”不意味着复用同一 Turn。Session 拥有远端对话连续性;每个 material attempt
+Session 拥有远端对话连续性;每个 material attempt
仍有自己的 Turn/effect identity、receipt 和 quota settlement。Read-only observe 则负责验证后置
条件,不为了凑治理形式额外扣一次 quota。
-这条链路的威力在于,最终结论不是“Agent 说它测过”,而是四种独立证据可以互相校验:
+这条链路的威力在于:
- governed journal 证明哪一个 exact request 被允许并执行;
- Session readback 证明用户可见事件确实出现;
- trace/runtime evidence 证明请求经过哪个实际运行版本;
- typed domain receipt 证明被测能力对应哪个结构化配置或 metadata 决策。
-任何一层冲突都应保持 `Unknown` 或让 Todo 继续 open,而不是用一个成功 marker 覆盖其余证据。
+任何一层冲突都应保持 `Unknown` 或让 Todo 继续 open。
### API 组合而不是万能 Executor
@@ -326,7 +325,7 @@ bounded request、binding、authority、receipt 和 settlement。领域逻辑因
| Receipt/readback/trace 冲突 | 选一个看起来成功的证据 | 保持 Todo open,刷新证据或 self-repair adapter |
| 相同 Turn 携带不同 request digest | 把它当普通 retry | fail closed,创建新的合法 Todo/Turn identity |
-因此,governed execution 的核心不是“所有调用都经过 LoopX”这一句口号,而是让每个 material
+因此,governed execution 的核心是让每个 material
external effect 都能回答:它属于哪个 Goal/Todo/Turn、provider 是否真的提交、LoopX 是否已写回、
quota 是否只结算一次,以及崩溃后下一步究竟是 retry provider 还是只 reconcile ledger。
@@ -355,7 +354,6 @@ loopx --format json configure-goal --goal-id
2. 阅读 exact delta 和 boundary;
3. 再显式 `--execute`;
4. 关闭 feature 时保留历史 evidence,只关闭未来行为;
-5. feature gate 不等于 runtime permission。
## Explore Graph:探索证据层
@@ -564,7 +562,7 @@ Router state 由 runner 在 epoch boundary 持久化。Harness 仍然只生成
## Single-Agent Auto ML:Graph、Harness 与 Domain Pack 怎样合起来
-Single-Agent Auto ML 不是缩小版 Auto Research。它只有一个长期 agent lane,却要同时处理:
+它只有一个长期 agent lane,却要同时处理:
- 候选实现与代码 revision;
- 训练/评估 provider 的异步 task;
@@ -664,7 +662,7 @@ repair/retry,不应 `refutes` 模型假设。Harness 下一轮消费这些边
### Promotion、Reward Memory 与系统能力演进
-Graph finding 和 Harness ranking 都不是 promotion authority。Promotion 至少需要:
+Promotion 至少需要:
```text
exact candidate/revision/window
@@ -753,8 +751,7 @@ loopx configure-goal \
## Reward Memory
Reward memory 是 per-agent、default-off 的实验能力,目标是让经过验证的人类评价和工程经验
-在后续 run 中被作用域化复用。它不是 LoopX canonical state 的替代品,也不是把聊天记录长期
-注入模型。
+在后续 run 中被作用域化复用。
| Memory class | 与 LoopX 当前状态的关系 | 允许产生的影响 |
| --- | --- | --- |
@@ -787,7 +784,7 @@ connector: 外部事件、权限、source authority
projection sink: 把 public-safe LoopX read model 显示到 Lark
```
-开启 inbox 不等于允许发送消息或自动写 goal。外部消息必须先经过身份、reply/mention relation、source authority 和 gate 检查,再转换为 bounded LoopX event/todo。
+外部消息必须先经过身份、reply/mention relation、source authority 和 gate 检查,再转换为 bounded LoopX event/todo。
Sink 应保留 lineage:
@@ -840,7 +837,7 @@ loopx --format json explore worker-branch-plan \
## 核心代码领读:Explore 与 Auto ML 怎样复用 kernel
-扩展层最重要的判断不是“功能多不多”,而是它有没有重新发明 todo、quota、lease、scheduler 或 evidence。下面沿真实配置与执行边界读。
+扩展层最重要的判断是它有没有重新发明 todo、quota、lease、scheduler 或 evidence。下面沿真实配置与执行边界读。
### 1. Feature config 默认关闭,preview 与 execute 分离
@@ -1084,7 +1081,7 @@ leader authority。
9. Material provider 是否以稳定 idempotency key replay,并把 start 与 reconcile 分开?
10. Receipt digest 是否在 quota spend 前 durable writeback?
11. Evidence 是否 compact、可追溯、符合 public/private boundary?
-12. Focused smoke 是否证明 shipped behavior,而不是临时字段?
+12. Focused smoke 是否证明 shipped behavior?
## 课程结束后的能力标准
diff --git a/docs/development/control-plane-course/README.md b/docs/development/control-plane-course/README.md
index b9515b1c68..c89179974f 100644
--- a/docs/development/control-plane-course/README.md
+++ b/docs/development/control-plane-course/README.md
@@ -15,7 +15,7 @@ Pack 增加领域泳道。看板只是 projection;canonical state 和 typed tr
贯穿全课的另一种判定是 effect interpreter:模型提出 effect request,harness 解释后返回
observation,再把 next effect 交回 host。每个状态机都是解释器内部的一张 interpretation
-table,而不是独立产品。
+table。
## 课程先建立一个递进
@@ -30,7 +30,7 @@ table,而不是独立产品。
-> CLI packet:把当前状态投影成这一次 bounded Turn 的过程协议
```
-这不是要把全部历史塞回模型,而是让有限上下文每次只接收当前 objective、必要 evidence ref、
+这是让有限上下文每次只接收当前 objective、必要 evidence ref、
合法 frontier 和 writeback contract。完整推导见[概念导读](00-concept-primer.md)。
## 三个 Showcase 是课程主线
@@ -62,7 +62,6 @@ Single-Agent Auto ML 还提供一条贯穿第 0、1、2、3、4、5、6、8、9
Explore Graph 把假设、实验、支持、反驳和负向结果保存成可追溯证据拓扑;Explore Harness
读取显式 Graph refs、当前 todo 和资源容量,给出 analysis-only 的候选组合;单个 Agent 仍必须经
普通 claim、quota、provider effect、monitor、validator 和 promotion gate 才能推进实验。
-Graph 不是执行 DAG,Harness 也不是隐藏 scheduler。
## 先边界,再逻辑,再代码
@@ -78,8 +77,8 @@ Graph 不是执行 DAG,Harness 也不是隐藏 scheduler。
| Write / replay | transition 在哪里提交,崩溃后从哪个 phase 恢复? | sequence、journal、state machine |
| Code / acceptance | 哪个函数实现规则,什么反例证明它没有被绕过? | 代码领读、smoke、常见错误 |
-这套顺序不是排版约定,而是评审方法。架构层没有明确 owner,技术层通常会复制状态机;
-逻辑层没有 receipt,测试往往只能证明函数跑过,不能证明 transition 已提交。
+这套顺序是评审方法。架构层没有明确 owner,技术层通常会复制状态机;
+逻辑层没有 receipt,测试往往只能证明函数跑过。
课程采用一条贯穿始终的架构边界:执行 runtime、memory provider 和 workspace storage
可以替换或协作,但 goal lifecycle、canonical state contract、验证与恢复闭环由 LoopX
@@ -108,10 +107,10 @@ vision / goal boundary
6. **回执**:外部动作是否形成了与原 proposal 绑定的 durable receipt?
7. **延续**:本轮之后是 runnable successor、明确等待、replan、repair,还是满足 terminal closure?
-控制面的复杂性通常不是缺少第八个字段,而是这七个问题被压进一个布尔值,导致一层
+控制面的复杂性通常是这七个问题被压进一个布尔值,导致一层
事实误替另一层做决定。
-课程不是 API 枚举。每一讲都包含四类材料:
+每一讲都包含四类材料:
- 一条真实 CLI 或状态执行路径;
- 一组核心代码领读入口,说明调用顺序、关键分支和不变量;
@@ -177,7 +176,7 @@ todo 和 evidence 的局部规则会在同一轮组合生效。
| benchmark postcondition + committed Turn + runner readiness | 结果通过为什么不能替代因果归因与控制面回执;测试替身怎样避免改写 meaningful operation 语义? | 第 6、8 讲 |
| external write + Turn journal + provider receipt + settlement checkpoint | 远端效果不确定时为何不能盲目 retry;什么时候应 replay provider,什么时候只能恢复 writeback 或 spend? | 第 6、8、11 讲 |
-这些组合不是额外功能清单,而是同一状态图的交叉切面。课程中的 case、decision table 和 smoke 应尽量覆盖交叉项,而不是为每个名词各写一个孤立 happy path。
+这些组合是同一状态图的交叉切面。课程中的 case、decision table 和 smoke 应尽量覆盖交叉项。
## 版本与边界
diff --git a/docs/development/control-plane-course/goal-control-state-kernel-packet-mental-model.md b/docs/development/control-plane-course/goal-control-state-kernel-packet-mental-model.md
index 27140074dc..035423fe46 100644
--- a/docs/development/control-plane-course/goal-control-state-kernel-packet-mental-model.md
+++ b/docs/development/control-plane-course/goal-control-state-kernel-packet-mental-model.md
@@ -3,7 +3,7 @@
> **结论:** Goal 给出稳定方向,structured control state 记录当前动态局面,Kernel
> 校验并提交合法的状态迁移,Packet 把当前局面编译成 Agent 这一轮可以执行的行动协议。
-这四个名称不是四个并列模块,也不是四份状态。最简单的记法是:
+最简单的记法是:
```text
Goal:要去哪
@@ -46,9 +46,7 @@ Packet:这一轮具体走哪一步
| Kernel | 状态迁移与恢复引擎 | authority 校验、transition 接受、writeback、replay、closeout | 状态文件、领域推理器或 Provider |
| Packet | 一次 Turn 的行动协议 | identity、selected work、允许/禁止动作、proof boundary、next command、writeback contract | 长期事实源或全部历史 |
-Kernel 不是状态本身,而是管理通用生命周期、校验写入并使状态可恢复的规则引擎。Packet
-也不是第二份状态,它只是从当前状态生成的一次性只读投影:Packet 丢失可以重建,canonical
-state 丢失则可能无法正确恢复。
+Kernel 是管理通用生命周期、校验写入并使状态可恢复的规则引擎。
外部系统仍然拥有各自的权威事实。例如 repository 拥有当前代码,Git host 拥有 PR 与
review 状态,CI 拥有检查结果。LoopX 保存的是:为什么观察这些对象、观察结果支持哪个判断、
@@ -89,7 +87,7 @@ flowchart TD
## Packet 由什么生成
-Packet 不是只从一条 Goal objective 生成,而是组合:
+Packet 是组合:
```text
稳定 Goal
@@ -101,7 +99,7 @@ Packet 不是只从一条 Goal objective 生成,而是组合:
+ Kernel 与 Capability 规则
```
-然后压缩成本轮有限上下文可以安全消费的工单。下面是概念示例,不是具体协议的完整 schema:
+然后压缩成本轮有限上下文可以安全消费的工单。
```yaml
packet:
@@ -124,7 +122,7 @@ packet:
```
Packet 必须足够薄,避免把全部历史塞回模型;也不能薄到遗漏 identity、authority、required
-proof 和 writeback。它是过程协议,不是普通提示词摘要。
+proof 和 writeback。
## 一次 Auto PR Issue Fix Turn
@@ -196,7 +194,7 @@ Replan 通常也不会随意改写最终 objective。它先修订路线、vision
## Result 为什么不能直接成为状态
-Agent 说“CI 已通过,建议合并”只是 result 或 proposal,不是 canonical truth。完整路径应是:
+Agent 说“CI 已通过,建议合并”只是 result 或 proposal。完整路径应是:
```text
Agent result
diff --git a/docs/development/control-plane-course/topic-long-horizon-convergence.md b/docs/development/control-plane-course/topic-long-horizon-convergence.md
index cd50811025..9808da4830 100644
--- a/docs/development/control-plane-course/topic-long-horizon-convergence.md
+++ b/docs/development/control-plane-course/topic-long-horizon-convergence.md
@@ -3,8 +3,7 @@
> **本讲结论:** 长程任务的稳定性不来自一次更长的推理,也不来自让 Agent 永远保持活跃。
> 它来自一组跨 Turn 持续成立的收敛合同:方向由 Vision、Goal 与 Acceptance 约束,工作由
> Frontier 选择,外部动作由 Authority 与 Receipt 约束,进展由 Durable Evidence Delta
-> 定义;当证据不再增加或路线失效时,系统进入 Wait、Replan 或 Self-Repair,而不是重复
-> 同一个动作。
+> 定义;当证据不再增加或路线失效时,系统进入 Wait、Replan 或 Self-Repair。
建议时长:60 分钟。问题定义 8 分钟、核心闭环 12 分钟、防跑偏 10 分钟、防循环 12 分钟、
双 Showcase 回放 10 分钟、接入边界与问答 8 分钟。
@@ -30,17 +29,10 @@ Judge 可以判断“是否完成”,却未必能告诉下一轮“路线为
2. 解释为什么 Turn 是执行窗口,Accepted Transition 才是进展单位;
3. 用方向、权限、证据、Delta、活性和终局六条不变量审查长程系统;
4. 解释 Replan、Self-Repair、Monitor Backoff 和 Explore 各自解决哪类停滞;
-5. 解释 successor todo 怎样把局部完成接回 Goal,而不是制造无限任务链;
+5. 解释 successor todo 怎样把局部完成接回 Goal
6. 把 PR Issue Fix 与 Auto Research 映射到同一套收敛闭环;
7. 判断 LoopX、领域 Capability、Provider、Evaluator 与现有 Agent Runner 分别必须提供什么。
-本讲不承诺:
-
-- 给任意模糊目标自动生成正确验收标准;
-- 让模型的每次方案判断都正确;
-- 用一个通用 planner 替代领域 evaluator;
-- 让 Graph、Harness、scheduler 或 supervisor 获得隐藏的执行权限;
-- 把“运行时间更长”直接解释为“结果质量更高”。
## 一小时讲授路线
@@ -146,7 +138,7 @@ external source of truth
| PR Issue Fix | `repo + issue_ref`、`repo + pr_ref` | feasibility、exact-head checks、review/merge state、notification receipt | 把旧 head 的绿色结果用于新 commit;重复处理已覆盖 review |
| Auto Research / ML Experiment | hypothesis/experiment、revision、window、evaluator contract | matched result、dev/holdout、guardrail、support/refute、promotion/retirement proposal | 只记当前最好分数;把 infra failure 当模型负证据;反复探索已证伪 family |
-Domain State 仍不是新的事实源、memory dump 或第二套 Kernel。GitHub、训练系统和 evaluator
+GitHub、训练系统和 evaluator
继续拥有外部真相;pack 只保存可重算、可比较、可幂等更新的紧凑 read model。下面的伪代码
展示这条窄边界:
@@ -177,7 +169,7 @@ schema 和 proposal 属于 pack,最终是否执行仍由 Kernel 判断。
[Domain Capability Packs](../../product/domain-capability-packs.md)和
[Issue-Fix State Kernel × Domain State 案例](../../../loopx/capabilities/issue_fix/docs/state-kernel-domain-state-case-study.zh-CN.md)。
-所以 LoopX 不是一个包办所有推理的“大 Agent”。它更像一个长期控制内核:领域层提供
+它更像一个长期控制内核:领域层提供
可判定事实,host 执行 bounded Turn,Kernel 维护跨 Turn 仍需成立的身份、权限、证据和
恢复合同。
@@ -210,9 +202,6 @@ schema 和 proposal 属于 pack,最终是否执行仍由 Kernel 判断。
这是目标漂移。每个实验都可能执行正确,但优化代理指标的过程已经离开原目标。
-两个失败的共同点,不是模型不够聪明,而是系统没有把“什么约束方向、什么构成新证据、
-什么变化才值得再花一轮”变成可继承的状态。
-
## 先区分四种运行状态
长程系统不能把所有未完成都称为“继续”。至少要区分四种状态:
@@ -224,7 +213,7 @@ schema 和 proposal 属于 pack,最终是否执行仍由 Kernel 判断。
| 目标漂移 | 局部代理目标开始替代 Goal/Acceptance | Vision checkpoint、acceptance audit、replan |
| 局部循环 | 动作重复,但没有新增信息、状态 Delta 或失败区分度 | Stop repeating、diagnose、replan 或 self-repair |
-“重复”本身不是错误。CI 从 pending 变成 failed 后再次处理是合法迭代;外部训练任务未结束时
+CI 从 pending 变成 failed 后再次处理是合法迭代;外部训练任务未结束时
按 due time 轮询也是合法等待。循环的判定依赖三件事:
1. 输入事实是否变化;
@@ -316,7 +305,7 @@ Progress = 与 Acceptance 相关的 durable transition
### 核心代码一:一轮怎样从 Decision 走到 Commit
下面是 `build_quota_should_run`、`build_interaction_contract` 与
-`run_loopx_turn_once` 的教学压缩版。它是结构化伪代码,不是稳定 Python API:
+`run_loopx_turn_once` 的教学压缩版。它是结构化伪代码:
```python
def advance_one_turn(status, goal_id, agent_id, host):
@@ -417,9 +406,6 @@ Todo 可以被替换,计划可以变化,Vision 也可以在新证据下被 p
### 权限不变量:Proposal、Effect 与 Commit 分开
-一个 Agent 可以提出 merge、promotion 或 launch proposal,不代表它有权执行;Provider 执行
-了外部 effect,也不代表它有权修改 Goal lifecycle。
-
```text
proposal
-> authority and scope check
@@ -489,8 +475,6 @@ progress。它们可以更新 cadence 或 compact counter,但不应消耗与
| Rolled back | activation 与 rollback receipt 均绑定 exact revision |
| Closed with gap | 剩余缺口、原因和不再继续的依据明确 |
-“没有更多想法”不是终态证据;“暂时看不到 Todo”也不是。
-
### 核心代码二:Terminal 是严格合取,不是 Todo 为空
下面的伪代码把终局审计压成一个可 review 的 predicate:
@@ -513,8 +497,7 @@ def terminal_ready(state):
```
实际系统还会按领域加入 merge、promotion、rollback 或 `no_followup` 证明,但结构不变:
-终局是多项权威事实的合取。任何一个计数或 readback 缺失,都应产生明确 gap,而不是让
-空 Frontier 冒充 Complete。
+终局是多项权威事实的合取。任何一个计数或 readback 缺失,都应产生明确 gap。
## 防跑偏:方向必须外置,但不能冻结
@@ -527,8 +510,7 @@ def terminal_ready(state):
| Acceptance | 什么证据允许宣称这一阶段完成? | 不直接执行验证或 effect |
| Todo | 下一步由谁、在什么条件下做什么? | 不自行改写长期方向 |
-这条约束链让计划可以灵活变化,同时保持目标连续。它也解释了为什么“写一份大计划然后一直
-执行”不是长程控制面:外部事实变化后,大计划会过期;没有 Vision 和 Acceptance checkpoint,
+这条约束链让计划可以灵活变化,同时保持目标连续。没有 Vision 和 Acceptance checkpoint,
Agent 只能在旧计划与新聊天之间猜测。
### Vision Checkpoint 不是例行总结
@@ -544,8 +526,7 @@ Material closeout 后,系统需要回答三个问题之一:
### Successor Todo:让局部完成留下可执行的下一段责任
-长程任务最常见的薄弱点,不是 Agent 做不完当前 Todo,而是它做完一个局部切片后,只留下
-“继续优化”“看看 CI”或“后续再处理”。这类自然语言意图没有稳定 identity、owner、触发
+长程任务最常见的薄弱点。这类自然语言意图没有稳定 identity、owner、触发
条件和 lineage;session 或 Agent 一换,局部成果就很容易被误判成 Goal 已完成。
Successor todo 把这段隐式意图改写成控制面事实:
@@ -566,7 +547,7 @@ Vision、Goal 或 Acceptance。Successor 只能说明“接下来由谁在什么
1. 创建并绑定 successor,当前局部证据明确说明它继续缩小哪个 Acceptance gap;
2. 写入 gate、monitor、blocker 或 `resume_when`,说明后继为什么暂时不可运行;
-3. 用 terminal evidence 明确记录 `no_followup`,证明不是因为 Agent 没想到下一步。
+3. 用 terminal evidence 明确记录 `no_followup`。
教学伪代码可以压成一个局部闭包合同:
@@ -589,9 +570,9 @@ def close_todo(parent, evidence, result, acceptance):
immediate action,必须显式 complete 或 defer;否则两个 Todo 都可能继续进入 quota。
- 不要为每个 shell command、Turn 或微小子步骤创建 successor。Successor 应出现在有
material closeout、owner/handoff 变化、外部等待或路线变化的语义边界;长链本身应触发
- Vision/Acceptance checkpoint,而不是继续机械加节点。
+ Vision/Acceptance checkpoint。
-因此,successor 机制提升工程质量的方式并不是“让 Agent 多干活”,而是迫使每个局部交付
+因此,successor 机制提升工程质量的方式并是迫使每个局部交付
同时交代证据、剩余缺口和下一段责任。它把“完成当前 PR”与“完成整个 Goal”之间原本容易
丢失的推理,变成可验证、可恢复、可审计的状态转移。
@@ -605,7 +586,7 @@ def close_todo(parent, evidence, result, acceptance):
| Todo | reproduce、patch、monitor、review correction | hypothesis、execute、evaluate、holdout、retire/retry |
| Forbidden proxy | “有新 commit”替代“issue 已解决” | “dev lift”替代“research acceptance 已满足” |
-方向锚点不是静态不变。Reviewer 改变 public contract、实验否定原假设、用户缩小目标范围,
+Reviewer 改变 public contract、实验否定原假设、用户缩小目标范围,
都可以触发 patch;变化必须形成带 source、scope 和 Delta 的状态,而不是只留在聊天里。
### 人的反馈也必须先分类
@@ -694,8 +675,7 @@ CLI 是状态与决策 truth;轻量 skill 或 system instruction 负责约束
- required gate 要给用户具体问题;
- quiet 时不制造 delivery。
-Codex、Claude Code、自研 Agent 或远端开发机可以用各自方式承载这些行为约束。Skill 的安装
-路径不是产品合同,CLI packet、state schema 和 receipt 才是。
+Codex、Claude Code、自研 Agent 或远端开发机可以用各自方式承载这些行为约束。
## 防循环:先判断“有没有增加信息”
@@ -713,8 +693,7 @@ Codex、Claude Code、自研 Agent 或远端开发机可以用各自方式承载
| 候选集中在同一近邻 family | exploration diversity 不足 | 应随机扩展所有分支 |
| dev 改善但 holdout 不变 | evaluator 或假设泛化不足 | 模型永远不可改进 |
-当前 LoopX 工作流常把连续两轮 no-progress 作为触发 Self-Repair 的操作性阈值。它不是所有
-领域的数学定律。昂贵实验、长时间构建和低频外部事件需要领域化 cadence;关键是 streak
+当前 LoopX 工作流常把连续两轮 no-progress 作为触发 Self-Repair 的操作性阈值。昂贵实验、长时间构建和低频外部事件需要领域化 cadence;关键是 streak
必须按 agent lane、monitor target 或 failure identity 归因,不能让一个 lane 的变化替另一个
lane 清零。
@@ -798,7 +777,7 @@ same action with no new basis -> retry loop
new evidence + route delta -> valid replan
```
-Replan 的价值不是“想一个新点子”,而是让下一轮看到不同的合法 Frontier。
+Replan 的价值是让下一轮看到不同的合法 Frontier。
### Replan 的真实复杂度:不是一个 Selector,而是一条可恢复控制链
@@ -832,7 +811,7 @@ Detect
| Settle | 什么变化足以证明没有原地打转? | Delta contract、frontier-scoped ACK、next Frontier |
这条链刻意没有一个“万能 planner”。Detector、Frontier policy、obligation builder、Quota
-和 writeback 各自保留边界。复杂度来自这些合同的组合,而不是来自一个超长函数。
+和 writeback 各自保留边界。复杂度来自这些合同的组合。
一小时现场主讲只需保留这张六层链、ordered rules 的三组优先级、Guidance/ACK 不一致
案例和后面的端到端 trace,约 10 到 12 分钟。下面“之一”到“之六”是讲师备课与课后下钻
@@ -901,7 +880,7 @@ facts = GoalFrontierReplanFacts(
3. **历史只能经 ACK 进入当前判断**:长 Todo 链是否已经被审视、watch lane 是否已确认,
不能从自然语言推断,只能读取带 Delta contract 的 durable ACK。
-所以 `Facts` 不是原始状态的字段搬运,而是一个 agent-scoped、authority-aware 的语义
+所以 `Facts` 是一个 agent-scoped、authority-aware 的语义
reducer。Selector 的确定性依赖这一层先把“谁的工作”“哪种 gap”“哪个 Frontier”归一化。
### 核心代码四之二:Frontier Replan 是有顺序的规则,不是自由发挥
@@ -1046,7 +1025,7 @@ if decision.rule in {MONITOR_NO_CHANGE_STREAK, MONITOR_FRONTIER_EXHAUSTED}:
- `agent_id`:谁有义务处理;
- `stall_threshold` 与 `trigger_count`:为什么现在触发;
-- `triggers`:可回读的证据,而不是一句“感觉卡住了”;
+- `triggers`:可回读的证据
- `todo_actions`:允许写回的最小动作;
- `stop_condition`:遇到 private material、credential、destructive git、production
action 或 owner-only decision 时停止;
@@ -1098,14 +1077,12 @@ derived = derive_goal_frontier_replan_obligation_from_summaries(
return projection(replan_obligation=derived or obligation)
```
-这里防止三种“伪完成”:
+这里防止“伪完成”:
1. **错 Agent ACK**:peer A 的 Replan 不能替 peer B 关闭 obligation;
-2. **旧 Frontier ACK**:相同文案再次出现,不代表仍是同一个 blocked successor;
-3. **过期 ACK**:ACK 早于最新 trigger evidence 时,不能证明新问题已处理。
因此 `autonomous_replan_ack_matches_frontier` 除了比较 `frontier_identity`,还会比较 ACK
-时间和 trigger 时间。ACK 是当前 obligation 的结算凭证,不是“历史上曾经授权过”的通行证。
+时间和 trigger 时间。ACK 是当前 obligation 的结算凭证。
### 核心代码四之五:Quota 把 Obligation 提升为 Must-Attempt
@@ -1127,7 +1104,7 @@ if autonomous_replan_obligation.required:
}
```
-它表达的是一项机器执行义务,而不是用户提醒。即使用户当前没有待办,Agent 也必须先处理
+它表达的是一项机器执行义务。即使用户当前没有待办,Agent 也必须先处理
Replan,再回到 monitor 或普通 advancement。反过来,若真正缺少 owner-only authority,
前面的 `open_user_todo` 或 gate rule 已经短路,不会把用户决策伪装成自主 Replan。
@@ -1163,7 +1140,7 @@ read_back_semantic_receipt()
spend_one_slot()
```
-classification、手工 ACK、读收据和 caller 自报 repair kind 都不是结算凭证。写时 gate
+写时 gate
先重算与 quota 相同的完整 goal frontier,再检查 typed delta;因此旧 periodic ACK 不能关闭
随后轮换出的 vision/frontier obligation,重复维护写回也不能落盘。
@@ -1191,7 +1168,7 @@ quota + refresh-state
对 `repeat_until_closed` vision,maintenance-only continuation 不能结算;对确实应该等待的
`as_needed` 场景,等待应留在有 cadence、expiry、resume condition 的 monitor Todo 生命周期
-中,而不是冒充 replan 成功。这个区分避免把“合法等待”与“方向改变”压进同一个 ACK。
+中。这个区分避免把“合法等待”与“方向改变”压进同一个 ACK。
### 端到端 Trace:为什么一次 Replan 之后还可能继续 Replan
@@ -1285,7 +1262,7 @@ Graph 和 Harness 应独立启用:
| on | on | 证据拓扑已经稳定,需要 advisory portfolio |
对 evaluator 尚不清楚、指标不可比较、资源 identity 不稳定的项目,先用 Graph 记录证据,
-不要急着启用 Harness。当前 Harness 的稳妥定位仍是只读规划器,不是自动 launch controller。
+不要急着启用 Harness。当前 Harness 的稳妥定位仍是只读规划器。
### 不需要先引入多层级 Agent
@@ -1335,7 +1312,7 @@ Executor 不能评价并 promotion 自己的 dev-only 结果。Explore Graph 也
### 门禁也要按风险分层
-不是每轮都运行最昂贵的 Judge。稳定 schema、transition rule 和 identity 先用 deterministic
+稳定 schema、transition rule 和 identity 先用 deterministic
test;真实 Agent 是否正确理解 packet,再用 actual-default model behavior gate;明确宣称
长程 outcome 提升时,才需要 matched stable/candidate baseline。
@@ -1368,7 +1345,7 @@ test;真实 Agent 是否正确理解 packet,再用 actual-default model beha
6. `head-A` 的 checks 通过后,merge 仍等待 scoped authority;
7. host 执行 merge 并 readback merged commit,terminal audit 关闭 monitor 与 successor。
-退出循环的关键不是“第三次终于改对代码”,而是失败被重新分类,新 Turn 增加了能区分代码
+退出循环的关键是失败被重新分类,新 Turn 增加了能区分代码
问题与环境问题的证据。
### 回放 B:Auto Research 怎样退出 dev-only 局部最优
@@ -1381,7 +1358,7 @@ test;真实 Agent 是否正确理解 packet,再用 actual-default model beha
6. `H2` 的 matched holdout 同时满足 metric 与 guardrail,形成 promotion candidate;
7. promotion gate 和 activation receipt 结算后,Goal 决定继续探索还是严格关闭。
-退出局部最优的关键不是随机增加更多 Agent,而是让负向证据真正改变候选空间。
+退出局部最优的关键是让负向证据真正改变候选空间。
## 自编排 Runner 的最小接入合同
@@ -1422,7 +1399,7 @@ Evidence refs,但不能替领域系统宣布收敛。
## 什么时候不应启用更复杂的规划
-下面几种情况适合先收缩问题,而不是增加 Agent 或 Harness:
+下面几种情况适合先收缩问题:
1. Acceptance 仍是一句价值判断,没有可观察的 proxy 与人工 gate;
2. Provider 不能返回稳定 task/effect identity;
@@ -1432,8 +1409,7 @@ Evidence refs,但不能替领域系统宣布收敛。
6. 一个 Goal/Frontier 尚未跑通,就准备增加多层 supervisor;
7. planner 输出会直接触发不可逆 effect。
-此时最有价值的工作通常是完善 Domain Pack、receipt、evaluator 或 public-safe evidence,
-而不是提高 branch width。
+此时最有价值的工作通常是完善 Domain Pack、receipt、evaluator 或 public-safe evidence。
## 当前能力边界
diff --git a/docs/development/design.md b/docs/development/design.md
index 5ff9dc5818..b741744357 100644
--- a/docs/development/design.md
+++ b/docs/development/design.md
@@ -103,7 +103,7 @@ Owner-facing state follows four rules:
another's observed activity. Distinguish a recent ended turn from execution.
Show missing coverage neutrally beside the Goal state, with each affected
Agent, host and read failure available through the shared contextual help.
- A cadence miss is an older observation, not proof of a stopped worker.
+ A cadence miss is an older observation.
- **Group by responsibility.** Collaboration surfaces place work under the
member, Agent or owner responsible for it, so one glance shows who is doing
what and who is blocked. Work with no resolvable owner goes into an explicit
@@ -207,7 +207,7 @@ the chart. Show one finding at a time with its declared status and full text;
keep all findings selectable and failed or tentative counts visible. Preserve
the exact finding event on reload and Back, including an earlier judgment later
revised under the same finding identity. Period selection opens the original
-event from that period; current-state projection does not replace its text. Offer the whole recorded history in place
+event from that period; Offer the whole recorded history in place
and through the existing return action, without letting it bury the chosen text.
When opening a specific finding, put its parent question in accessible contextual
help rather than another collapsed title row. Opening a route's question still
@@ -299,11 +299,10 @@ model or rewrite a saved result. Record remaining content failures in the
existing task and review.
译文验收须对照原文及引用语境,核对数量所指、否定和不确定性。字段齐全、原始标记
-未变,不代表含义已经清楚。有来源支持的数量用界面语言正文说清,不能只留下括号内
+未变。有来源支持的数量用界面语言正文说清,不能只留下括号内
的连写英文;准确原词仍可查,含义不明的计数、单位和标识不猜测。修订沿版本化分析
处理,评审不自动重跑模型或覆盖已存结果;剩余正文问题记入原任务和评审。
-
刷新和前进后退保留视图、时间分组与证据焦点;标签之间保留阅读位置。选择状态按
Goal 和来源隔离。研究中从侧栏切换 Goal 仍停留在研究页,读取新 Goal 自身证据;
返回恢复原 Goal 的选择。首页及任务、会话、成果的明确链接保留各自目的地。
@@ -584,8 +583,7 @@ keys do not define tokens. PostCSS and its declared value parser distinguish
stylesheet declarations and variable functions from quoted examples, comments
and other declaration values. Parse errors fail the check.
-This is a syntactic inventory: it does not prove runtime reachability, resolve
-object spreads or aliases, or model CSS inheritance and selector scope. Tokens
+Tokens
that are genuinely optional may keep a fallback (`var(--pw-surface, #fff)`).
### Type Scale
@@ -924,7 +922,6 @@ For feature development, carry one user task through the
A visually consistent composition must also eliminate unnecessary re-entry and
confirmation, identify the affected target, and show truthful state after action.
-
For UI implementation, migration, or reproduction:
1. Read this file before editing.
diff --git a/docs/development/documentation-layout.md b/docs/development/documentation-layout.md
index f1431d1f61..a5f3c27366 100644
--- a/docs/development/documentation-layout.md
+++ b/docs/development/documentation-layout.md
@@ -140,8 +140,7 @@ binary evidence. The old `examples/personal-workspace-browser/evidence/` and
Before removing a pack, inspect references across documentation, navigation,
source code, tests and distribution/build scripts, including references to its
README or manifest. Preserve transitive consumers and distinguish fixture reads
-from screenshot output paths. No static references is a review signal, not proof
-of disuse. Repair current links in the same change, preserve the bytes of retained
+from screenshot output paths. No static references is a review signal. Repair current links in the same change, preserve the bytes of retained
assets, and run the relevant link/asset checks. Retire tests only under the
[smoke retention rules](good-smokes.md), not because their files are large.
diff --git a/docs/development/frontend-delivery.md b/docs/development/frontend-delivery.md
index 0affd9b255..947f0defc8 100644
--- a/docs/development/frontend-delivery.md
+++ b/docs/development/frontend-delivery.md
@@ -16,8 +16,7 @@ the control plane or change the installed runtime.
For owner-authorized reads of existing runtimes, shared access lives in
`loopx.control_plane.status.goal_source`. Native status and Explore owners retain
-their semantics; this Python IO provider adds neither decisions nor lifecycle
-authority. Connection (`local` or a configured `ssh` alias) is independent of
+their semantics; Connection (`local` or a configured `ssh` alias) is independent of
environment (`host` or a container pinned by its full physical id), so a remote
container uses the same reader. It never starts a container, tunnel or worker.
@@ -95,8 +94,7 @@ source-namespace-isolated store; it creates no Goal mirror or source mutations.
The adapter uses one local Python process with one HTTP listener/thread per
prepared source. Cache misses invoke the source's native status CLI or bounded
log read; no lower CPU, process or IO cost is implied. Local host/container
-readback and SSH command composition are separate validation boundaries; a
-composed command test does not prove a live remote host/container journey.
+readback and SSH command composition are separate validation boundaries.
### Native App source Goals
@@ -145,8 +143,7 @@ through the original Goal's native history, including versions outside the
status window. Its default overview spans all retained records by recorded time;
it never silently selects the latest version. Sources proven to have no Explore
records show this overview directly. Other sources keep their Explore history
-and load strategy history only on request. Unknown times stay visible, and time
-adjacency establishes neither inactivity, inheritance nor causal benefit.
+and load strategy history only on request. Unknown times stay visible.
It preserves original language, negative results and unresolved
questions. The focused reader supports exact-version links, reload, Back/Forward
and unavailable-version recovery; missing versions never select the latest one
@@ -211,9 +208,7 @@ to make the display work. Label the link as historical, preserve the source byte
and retain the old namespace's artifacts. Admit the replacement through the same
source-link owner; its new physical namespace must invalidate old cursors and
analysis selection. Re-register an existing evidence pack only after verifying
-its original run/window, hashes and literal excerpts. Neither recovery nor
-registration starts analysis or turns an old native measurement into a current
-or countable study result.
+its original run/window, hashes and literal excerpts.
## Finding original steward delegations
@@ -240,8 +235,7 @@ only when **Linked work and records** is expanded, through the same authorized
reader and current request revision. It is a separate current observation, not
part of the request ordering/paging digest. Original conversations remain readable
through their existing complete-history reader. The 2,000-entry discovery bound
-and explicit incomplete coverage remain; this change does not claim an unbounded
-history index or an atomic snapshot.
+and explicit incomplete coverage remain.
Inventory and original-history HTTP reads both pin the shared runtime code
revision once per request. Without that boundary, every collaboration rule on a
@@ -253,7 +247,7 @@ are reread. It caches no authorization or completion decision.
在管家页头打开**委派**,输入请求内容、Goal、Agent 或请求 ID 后点**搜索**。
查询不区分大小写,匹配原始问题及当前交办的目的/背景,先筛选再分页。
**全部记录**包括已回传和已取消的请求;展开可回看交办、关联工作及原对话。
-**清空**恢复列表。页头数量仍表示全部待跟进请求,并非搜索命中数;读取不完整
+**清空**恢复列表。页头数量仍表示全部待跟进请求;读取不完整
时保留提示,**重试**沿用当前查询。搜索沿用既有来源授权和扫描上限,不确认、
取消或执行任何请求。
@@ -288,8 +282,7 @@ instead of following the latest message to the end.
The read projection requires the original Session, Turn and both existing
transport/Core correlation receipts. Canonical messages, model input and history
cursors remain unchanged. Missing, changed or unsupported frozen context keeps
-the full original message visible. Browsing neither replays work nor contacts the
-provider to fill missing context.
+the full original message visible.
外部原会话和委派的**原对话**优先显示用户原文,**引用与话题上下文**默认折叠。
展开后可读准确引用和按原顺序保存的话题节选,长内容不会跳到末尾。节选标记保留,
@@ -595,7 +588,7 @@ order only, without changing Goal priority, lifecycle or execution.
The existing TypeScript ordering functions remain the semantic owner. The
Python presentation adapter validates and atomically stores the list under a
-file lock; it is not a capability configuration namespace. Existing same-origin
+file lock; Existing same-origin
browser preferences migrate only when the durable source has no value. An old
origin's inaccessible browser storage cannot be recovered automatically. Read
or save failure keeps the current page usable and displays unsaved feedback;
@@ -605,8 +598,7 @@ although that runtime continues to use its browser-local preference.
The packaged `navigation-sorting` browser scenario uses synthetic workspace
records with the real HTTP preference owner. It checks pointer/keyboard moves,
refresh, service restart on another port, delayed hydration, rapid moves,
-failure/retry and browser-cache migration. It does not certify native WebView
-crash recovery or an already-installed App's adoption of a proposed PR.
+failure/retry and browser-cache migration.
## PR qualification and releases
diff --git a/docs/development/good-smokes.md b/docs/development/good-smokes.md
index 7c9676753a..ac48914673 100644
--- a/docs/development/good-smokes.md
+++ b/docs/development/good-smokes.md
@@ -84,9 +84,9 @@ contract. Before removing or combining a smoke:
6. rerun the focused entries plus fleet or catalog checks to prove that the
inventory has no coverage gap.
-名称相似或 setup 相同,并不能证明两个 smoke 保护同一合同。删除或合并前,应分别写明
+名称相似或 setup 相同。删除或合并前,应分别写明
不变量、公开入口、反例、运行频率和定向 profile;把完全相同内容和直接嵌套执行当作
-审阅候选,而不是自动删除指令。可以复用 canary harness 中的 fixture 或 subprocess
+审阅候选。可以复用 canary harness 中的 fixture 或 subprocess
setup,但不要因此合并不同的语义断言。去掉 smoke 调用另一个 smoke 的 wrapper,让每
个合同只运行一次且仍可独立选择,最后重跑聚焦入口以及 fleet/catalog 检查,确认清单
没有覆盖缺口。
@@ -124,7 +124,7 @@ a dated research note, candidate ranking packet, temporary run review, or
transitional benchmark decision. Keep that information in the research document
and cover shared invariants with a data-driven aggregate smoke.
-Smoke 超过约 500 行时,应重新检查它是否混合了多个测试;这不是自动删除或失败阈值。
+Smoke 超过约 500 行时,应重新检查它是否混合了多个测试;
将可复用行为放回产品 owner,使 smoke 保持轻量;较小测试无法覆盖真实端到端 adapter
合同时,仍可保留大型 integration smoke。不要用一次性 smoke 固化过期研究笔记、候选
排名、临时运行评估或阶段性 benchmark 决策的精确文案;这些信息留在研究文档,共有
diff --git a/docs/development/lexical-retrieval.md b/docs/development/lexical-retrieval.md
index ead87beb15..cd8670158e 100644
--- a/docs/development/lexical-retrieval.md
+++ b/docs/development/lexical-retrieval.md
@@ -24,7 +24,7 @@ The fixed algorithm is BM25 with k1=1.2, b=.75 and positive Lucene IDF.
Casefolded Unicode word tokenization splits underscores. Repeated query terms
do not boost scores. No synonyms, embeddings, segmentation service, discovery,
storage, configuration, network or Goal authority are introduced. Ranking is
-corpus-relative; a score does not certify a fact, risk, investment edge or trade.
+corpus-relative.
Historical consumers must supply only their visible corpus: future documents
would otherwise change document frequencies even if hidden from the results.
@@ -169,7 +169,7 @@ controlled by this small driver, so timing samples are descriptive. It generates
no answer and measures no causal task utility. The suite/report formats are
local experiments, not new Core contracts.
-Manual recall does not enable automatic memory. Current explicit instructions
+Current explicit instructions
belong to Semantic Preference; qualified procedural advice uses existing
`agent-turn-recall` after admission, and verified-outcome writeback remains
separate. Material recall still requires source rebase. No frontend comparison
@@ -185,5 +185,5 @@ No new automatic capability hook or UI/Lark configuration is enabled.
自修复 skill 保留解析器、准确 pattern/code 优先级和完整正文展开。现有 workflow
installer 和 wheel 将规范评分器打包到脚本旁,隔离运行仍无需 PATH 中的 LoopX。
-打包副本是构建/安装产物,不是第二份实现。金融消费者保留规范资产、字面匹配规则、
+打包副本是构建/安装产物。金融消费者保留规范资产、字面匹配规则、
信源/时点/lifecycle 边界和决策权威。不启用新的自动 capability hook 或 UI/Lark 配置。
diff --git a/docs/development/project-code-tour.zh-CN.md b/docs/development/project-code-tour.zh-CN.md
index 60ceef7f7f..fa647b3c14 100644
--- a/docs/development/project-code-tour.zh-CN.md
+++ b/docs/development/project-code-tour.zh-CN.md
@@ -13,7 +13,7 @@ LoopX 是一个运行在 Codex、Claude Code、Cursor 等 Agent harness 之上
- **Agent**负责完成一次具体工作;
- **LoopX Kernel**负责决定下一步是否合法、是否需要等待、是否需要询问人,以及如何从中断中恢复。
-本文讲的是“项目怎样工作”,不是逐个枚举所有 CLI 命令。仓库的命令面很大,第一次阅读应先抓住主干,再按需要深入能力包和扩展。
+本文讲的是“项目怎样工作”。仓库的命令面很大,第一次阅读应先抓住主干,再按需要深入能力包和扩展。
## 业务背景:为什么需要一个控制面
@@ -131,7 +131,7 @@ loopx/
## 四种运行责任:不要把边界读混
-LoopX 的目录分类和运行责任不是同一个维度。阅读一条调用链时,先问“谁拥有哪一类事实”:
+阅读一条调用链时,先问“谁拥有哪一类事实”:
| 角色 | 负责什么 | 明确不负责什么 |
| --- | --- | --- |
@@ -199,7 +199,7 @@ adapter_id: ...
后面还有 Authority Sources、Operating Contract、Non-Goals、User Todo、Agent Todo、Next Action 和 Progress Ledger。它不是普通笔记,而是后续 Agent tick 要读取的持久状态。
-Bootstrap 还会维护 Registry 条目。Registry 记录 Goal id、项目路径、adapter、状态文件、authority source、spawn policy、write scope 等信息。注意这里的 `write_scope` 是边界声明,不是自动授予外部系统权限。
+Bootstrap 还会维护 Registry 条目。Registry 记录 Goal id、项目路径、adapter、状态文件、authority source、spawn policy、write scope 等信息。注意这里的 `write_scope` 是边界声明。
## 一次典型场景:从 Goal 到下一轮 Turn
@@ -276,7 +276,7 @@ Quota 结果会被压缩成一个面向 Host/Agent 的 packet。关键字段通
| `capability_gate` | 是否需要领域能力、用户批准或额外检查。 |
| `todo_write_hint` | Todo 写回时需要遵守的最小协议。 |
-这些字段是“当前 snapshot 的编译结果”,不是新的事实源。下一次运行仍应从 Registry、Goal State、Authority Store 和运行历史重新生成。
+这些字段是“当前 snapshot 的编译结果”。下一次运行仍应从 Registry、Goal State、Authority Store 和运行历史重新生成。
### 第 3 步:构造 Turn Plan
@@ -292,7 +292,7 @@ Turn Driver 把 quota packet 转成 Host 可以执行的计划,主要绑定:
- 子 Agent 的上下文与允许的 child operation;
- 后续 transaction plan 和 settlement identity。
-这里有一个重要原则:**Turn plan 是一次执行的合同,不是执行结果。** 计划中写了要做什么,结果必须回来后再经过 schema、phase 和 identity 校验。
+这里有一个重要原则:**Turn plan 是一次执行的合同。** 计划中写了要做什么,结果必须回来后再经过 schema、phase 和 identity 校验。
### 第 4 步:Host 执行有界工作
@@ -311,7 +311,7 @@ Host request 会携带本轮允许的上下文、工作目录边界、执行模
- 不需要 spend 的结果是否错误地写入了 quota spend;
- durable completion 是否指向了预期 Todo,以及 continuation 是否为 successor、active goal 或 no-followup。
-`run_loopx_turn_once` 再按阶段运行 Host、任务 validator 和 typed settlement。它的返回值不是“模型说完成了”,而是带有可追溯 identity、完成阶段和结果类型的结构化结果。
+`run_loopx_turn_once` 再按阶段运行 Host、任务 validator 和 typed settlement。它的返回值是带有可追溯 identity、完成阶段和结果类型的结构化结果。
> 📦 **额外知识:bounded Turn 的边界在哪里?**
>
@@ -343,7 +343,7 @@ validation
> 📦 **额外知识:Idempotency(幂等)怎么理解?**
>
-> 同一个带 identity 的提交重复到达时,系统应识别“这是同一件事的重试”,而不是再创建一份新的事实。LoopX 通过 effect id、Todo/Turn 绑定、completed phase 和 receipt 来实现这种判断,而不是依赖“最近一次运行看起来像成功”。
+> 同一个带 identity 的提交重复到达时,系统应识别“这是同一件事的重试”。LoopX 通过 effect id、Todo/Turn 绑定、completed phase 和 receipt 来实现这种判断。
### 第 6 步:写回运行历史与事件投影
diff --git a/docs/development/returned-files-readback.md b/docs/development/returned-files-readback.md
index 39346b2ee0..650dd1f65b 100644
--- a/docs/development/returned-files-readback.md
+++ b/docs/development/returned-files-readback.md
@@ -13,8 +13,7 @@ same original-message download route.
## Source and byte checks / 来源与字节校验
- History joins the original Session, Turn and return route, then reuses
- `inspect_result_identity` and the TypeScript result-publication owner. The
- projection changes neither the message journal nor publication receipts.
+ `inspect_result_identity` and the TypeScript result-publication owner.
- A download repeats those checks and uses `read_result_file` to verify the
bounded, no-follow immutable snapshot's size and SHA-256. A mutable workspace
file is never the download source. An unavailable snapshot returns HTTP 503;
diff --git a/docs/development/status-service-readiness.md b/docs/development/status-service-readiness.md
index b617dec486..73c3a19f2a 100644
--- a/docs/development/status-service-readiness.md
+++ b/docs/development/status-service-readiness.md
@@ -25,9 +25,7 @@ fingerprint behavior. Advertising readiness but omitting its result fails closed
This is a bounded existing-service prerequisite for
[#3930](https://github.com/huangruiteng/loopx/issues/3930), not the unified daemon
-contract or complete M1 delivery. It does not establish service-profile identity,
-validate individual Goals, prove writable storage, qualify launchd lifecycle,
-or assert Chat/provider readiness. Profile identity, supervisor composition and
+contract or complete M1 delivery. Profile identity, supervisor composition and
migration remain separate implementation work.
To diagnose failure, repair the registry selected by the service and retry the
diff --git a/docs/development/testing-and-quality.md b/docs/development/testing-and-quality.md
index de05097fd2..2439ec2b9a 100644
--- a/docs/development/testing-and-quality.md
+++ b/docs/development/testing-and-quality.md
@@ -85,7 +85,7 @@ refreshed golden.
测试先判断状态和规则是否正确,再验证实现是否符合。预期结果必须来自独立审阅的
不变量,不能由被测实现或当前输出生成。Characterization fixture 只记录历史
-行为,不授予其正确性;发现矛盾时应修复规则并增加反例或 mutation 覆盖,不得刷新
+行为;发现矛盾时应修复规则并增加反例或 mutation 覆盖,不得刷新
golden 来让测试通过。
### State Composition Qualification / 状态组合验证
@@ -100,8 +100,7 @@ checks, real-backend gates and required validation remain in force.
跨领域状态机变更沿[组合验证 RFC](../architecture/rfcs/composable-state-machines-recovery-verification-v0.zh-CN.md)
选择有界旅程,复用 quality catalog 与已有验证矩阵。记录独立不变量、探索的 actor/
-resource 数与轨迹上限、故障顺序、真实入口/回读证据及有条件推进前提。有界序列
-检查不等于无界活性证明;既有确定性检查、真实后端门禁与必需验证继续适用。
+resource 数与轨迹上限、故障顺序、真实入口/回读证据及有条件推进前提。既有确定性检查、真实后端门禁与必需验证继续适用。
For a selected typed-core replacement, check illegal combinations at compile
time and malformed/historical input at runtime. Compare pinned base/head through
@@ -111,8 +110,7 @@ Retain only durable counterexamples, and do not build a general harness when an
existing conformance family can express the causal sequence.
选中的 typed core 替换同时验证编译期非法组合与运行时损坏/历史输入。相同公开
-路径比较 pinned base/head,用历史失败或语义 mutation 证明敏感性;候选实现生成
-的 golden 不是 oracle。只保留持久反例;已有 conformance 测试族能表达因果序列时,
+路径比较 pinned base/head,用历史失败或语义 mutation 证明敏感性;只保留持久反例;已有 conformance 测试族能表达因果序列时,
不另建通用 harness。
## Pull-Request Baseline / PR 基线
@@ -234,7 +232,7 @@ CI Maintenance 清理任务处理 closed 与 synchronize 事件(更新规则
`always()` 汇总使用强制取消 API。普通及强制取消前都重读目标 PR 和同源分支的
开放 PR;新出现的共享分支 PR 或读取失败会阻止副作用,分支不再共享后可重新
触发清理。清理需要一个短 runner 任务;这会释放过期
-容量,不等于为发布预留容量或设置 GitHub 共享池优先级。
+容量。
The [job exemption policy](ci-impact-selection.md) additionally permits pure
Dashboard-client changes to skip backend Python/Windows and Stage2c, while
@@ -268,7 +266,7 @@ implementations share the new rule is not a before/after compatibility test.
重构评审必须区分“相同判定”和“相同可观察语义”:同样拒绝但丢失对象状态或修复
提示仍是回归;新增认领前提可能阻断旧实现允许的未认领文案修正;`--note` 被 parser
-接受或出现在成功响应中,也不能证明它经过 dispatch 后落盘并能独立回读。先从旧调用
+接受或出现在成功响应中。先从旧调用
方及公开契约列出合法/非法分支,再运行基线与精确 head 的对照,不从新实现生成期望。
Show regression sensitivity: the focused case must fail on the historical
@@ -342,8 +340,6 @@ as nonblocking performance risks for default SQLite delivery, with their actual
values, source and limits. They are not passing checks. When the maintainer
revises a previously declared profile, record a new scoped qualification and
the reason; retain the original failed observation and its original criteria.
-This rule changes neither performance thresholds nor frozen benchmark/scoring,
-resource, deadline or promotion contracts.
默认交付按实际发布的默认执行/存储 profile 取得性能资格;当前新建本地 Goal
由既有 `goal_storage` owner 默认选择 SQLite。对真实 SQLite 入口、完整负载及
@@ -430,8 +426,8 @@ lease。私有快照和原始输出不得进入 Git 或公开 review;快照演
#### Isolate the managed Effect process as well as the data
-A separate worktree, registry, `--runtime-root` or archive `--destination`
-isolates neither CPU work nor the managed Effect server. Its discovery directory
+Isolate the managed Effect server's discovery directory alongside the worktree,
+registry, `--runtime-root` and archive `--destination` paths. Its discovery directory
uses Python's temporary directory and user identity; the server is selected by
source fingerprint. Identical checkouts and an installed release can therefore
share the same process. A large restore/audit can delay ordinary CLI requests
@@ -449,14 +445,13 @@ that isolated runtime after its requests settle, retaining the same temporary
environment for shutdown; never restart a live server as test cleanup.
For namespace disposal, call `restart_effect_runtime(wait_for_exit=True)` and
-require `stopped` before removing files. A closed listener or a zombie process
-group leader does not prove that all runtime threads have exited. A PID that is
+require `stopped` before removing files. A PID that is
still present returns `shutdown_pending`; retain the namespace and retry after
the process exits and its parent reaps it. The ordinary restart action still
uses serving-locator retirement.
删除隔离目录前,调用 `restart_effect_runtime(wait_for_exit=True)` 并确认返回
-`stopped`。端口关闭或进程组长成为僵尸进程,都不能证明其他线程已经退出。
+`stopped`。端口关闭或进程组长成为僵尸进程。
PID 仍存在时返回 `shutdown_pending`;保留目录,等进程退出并由父进程回收后再试。
普通重启操作仍按服务 locator 的退役状态判断。
@@ -477,10 +472,8 @@ repository identity.
Process isolation still shares machine resources. Run matched timing arms
sequentially without overlapping builds or recovery work. If interference is
discovered, retain failures and durable-receipt evidence, mark latency samples
-contaminated and resample after quiescence. A client timeout does not prove its
-server operation stopped; do not launch a duplicate restore while the first
-request may still be running. Neither a successful restore nor a clean resample
-qualifies concurrent administrative-work fairness or elapsed soak.
+contaminated and resample after quiescence. Do not launch a duplicate restore while the first
+request may still be running.
独立 worktree、registry、`--runtime-root` 或 archive `--destination` 不会隔离
Effect 后台进程;相同源码指纹可能让源码环境与已安装版本共享进程。演练前创建私有
@@ -489,7 +482,6 @@ Effect 后台进程;相同源码指纹可能让源码环境与已安装版本
重型操作前核对服务 PID 与活跃服务不同。等请求结束后,只在同一临时环境中停止
演练进程。进程隔离不消除整机资源竞争:耗时对照顺序运行,发现竞争则保留失败与
回执、作废受污染耗时并重新采样;超时不能当作服务端已停止,也不能因此重复恢复。
-恢复成功不证明并发管理操作公平性或自然时间 soak 已合格。
The Effect server drains admitted handlers before retiring. With compilation
caching enabled, its final synchronous cache flush has a one-second allowance,
@@ -538,16 +530,14 @@ Windows 文件锁只在已观察到争用后,对独占创建返回的 `EPERM`
Smoke cleanup owns every valid runtime locator in its newly created private
temporary namespace, including runtimes loaded by temporary base checkouts.
It uses the existing authenticated shutdown protocol, then observes actual
-process exit before deleting the namespace; serving-locator turnover alone
-does not establish that Node has finished its exit-time cache writes. Namespace
+process exit before deleting the namespace; Namespace
and locator symlinks are not followed. A cleanup failure retains the fixture
and reports a failed check with the original command output. Operator restart
keeps its existing serving-handoff semantics. This fixture repair does not
qualify native intermittent failures or sustained operation.
Smoke 清理覆盖新建私有临时目录中所有合法 runtime locator,包括临时基线 checkout
-启动的进程。它复用既有认证 shutdown,等实际进程退出后再删目录;定位文件退休不代表
-Node 的退出缓存写入已经结束。清理不跟随 namespace 或 locator 符号链接;无法证明
+启动的进程。它复用既有认证 shutdown,等实际进程退出后再删目录;清理不跟随 namespace 或 locator 符号链接;无法证明
退出时保留 fixture,以失败结果报告并保留原命令输出。操作员 restart 仍沿用既有服务
交接语义;该 fixture 修复不认证原生间歇故障或持续运行。
@@ -575,7 +565,7 @@ fields. A large real-state snapshot does not exercise commands synthesized only
inside an executor: run unchanged production caller chains, including reclaim,
replay and stale-writer rejection, before claiming caller closure. Persistent
public grants and clock-authorized ephemeral executor grants are separate
-contracts; neither a broad allowlist nor agreement across providers proves parity.
+contracts.
迁移决策 owner 时,既要盘点状态字段,也要盘点命令生产者。真实大快照不会自动覆盖
executor 内部生成的 reclaim 等命令;必须运行未改动的完整调用链,包括接管、重放和
@@ -659,7 +649,7 @@ packages outside the selected extras: do not change a worktree's environment
while another process is using it. Existing full-suite and CI commands below
continue to use `test`.
-`test-core` 仅用于显式选择的测试文件,不代表完整测试通过。MCP、Docker、图片
+`test-core` 仅用于显式选择的测试文件。MCP、Docker、图片
渲染、覆盖率和类型检查继续使用完整的 `test`。后续 `uv run` 也需指定
`--extra test-core`,保持环境一致。`uv sync` 可能移除所选依赖组之外的包,
因此不要修改正在被其他进程使用的工作区环境。下方完整验证及 CI 命令继续使用 `test`。
@@ -715,8 +705,7 @@ Use the app's existing installation and validation commands when required.
不删除文件、不改变构建流程;需要安装或验证时,继续使用应用原有命令。
Clean old dependency environments separately after checking worktree ownership,
-active users and recoverable dependency definitions. Age alone is not evidence
-that an environment is unused. Keep this an explicit maintenance operation.
+active users and recoverable dependency definitions. Keep this an explicit maintenance operation.
旧依赖环境另行清理:先核实工作区归属、使用中的进程,以及依赖定义能否恢复。
目录较旧不能证明无人使用;清理应作为显式维护操作进行。
@@ -725,8 +714,7 @@ that an environment is unused. Keep this an explicit maintenance operation.
`loopx/control_plane/` and `loopx/zcode_goal_mode/`, including standalone bridges
launched from Python and control-plane test drivers. New source files in these
owners need no per-file compiler registration. Tests and examples retain their
-explicit compile entries; this does not claim every TypeScript test is
-typechecked. `npm run test:control-plane` separately discovers and executes
+explicit compile entries; `npm run test:control-plane` separately discovers and executes
`tests/control_plane_ts/*.test.ts`.
`npm run typecheck:control-plane` 按既有目录发现全部控制面与 ZCode TypeScript
@@ -759,7 +747,7 @@ restart a shared service to repair a source-validation mismatch.
继承的 `PYTHONPATH` 也可能让 `uv run loopx` 越过可编辑安装,加载其他源码。
控制台脚本从 scripts 目录启动,而 `python -c`、`python -m` 会把当前目录放在
-导入路径前面;后两者导入成功不能证明控制台进程正确。POSIX 下源码验证可使用
+导入路径前面;POSIX 下源码验证可使用
仅对本条命令生效的 `env -u PYTHONPATH uv run --extra test loopx ...`;在仓库外
启动的测试子进程应显式将 `PYTHONPATH` 绑定到被测 checkout。验证真实控制台及其
语义结果,并与安装版验收分开;不要为源码验收偏差修改共享环境、提升安装版或
@@ -844,7 +832,7 @@ and record the actual source and argv. A matching version string alone is not
source provenance. Isolated CLI test launchers should likewise pin the checkout;
they must not accidentally qualify an installed release.
-上面的检查只说明该 Python 调用的来源,不能证明另一个 console script 的来源。
+上面的检查只说明该 Python 调用的来源。
继承的 `PYTHONPATH` 可能让已安装版本优先于 worktree;在仓库根目录执行 `python -c`
又可能掩盖差异。源码验证使用上述模块入口,并仅在该子进程内把当前目录放到导入路径
首位;保留其他设置,记录实际源码和 argv,不凭相同版本号判断来源。隔离 CLI 测试的
@@ -978,8 +966,7 @@ Full Python shards also opt into `--ci-stall-after 120` on the existing pytest
observer: a long-running test attempts to print its executing thread's Python stack without
terminating it or changing its result. This cooperative diagnostic needs the
interpreter to schedule its observer thread; it does not diagnose native code
-that holds the GIL indefinitely. The dump is diagnostic evidence, not proof that the last named test
-caused a stall. Reproduce with `-p scripts.ci.pytest_timing --ci-stall-after 120`; omit
+that holds the GIL indefinitely. The dump is diagnostic evidence. Reproduce with `-p scripts.ci.pytest_timing --ci-stall-after 120`; omit
`--ci-stall-after` or set it to `0` to keep this default-off diagnostic disabled. This grants no authority to
inspect other processes. Large text-boundary fixtures use short parameter IDs
so verbose progress records their cases without printing the payload.
@@ -1011,7 +998,7 @@ JUnit、coverage 或必过门禁。归属与测量边界见
超过该时长就尝试输出其执行线程的 Python 栈,不终止测试或改变结果。此协作式诊断
需要解释器调度观察线程,无法诊断始终占有 GIL 的原生代码。栈用于诊断,不能只凭
最后一个测试名认定卡顿根因。本地加 `-p scripts.ci.pytest_timing --ci-stall-after 120`
-复现,省略此参数或设为 `0` 可保持默认关闭;它不授予检查其他进程的权限。大文本边界 fixture 使用简短参数 ID,详细进度保留用例身份,
+复现,省略此参数或设为 `0` 可保持默认关闭;大文本边界 fixture 使用简短参数 ID,详细进度保留用例身份,
不打印整个载荷。
每次触发栈输出时,使用同解释器的隔离 writer,100ms 自行退出;父进程另设
500ms 通信期限,超时则终止并回收。管道背压不会改变共享 stderr 标志或留下
@@ -1129,7 +1116,7 @@ Binary images are outside the public-boundary **text** scan. Premerge lists
each changed raster image in `selection_inputs.visual_review_paths` and the
existing `manual_holds`, including image-only changes outside documentation
directories. Text checks can pass while the overall gate remains
-`manual_review_required`; this does not certify image privacy or permit merge.
+`manual_review_required`.
Inspect the exact revision's pixels, embedded metadata and source in the
existing PR review, and retain public-safe first-screen evidence in the PR
description. Do not add another presentation-confirmation round. Unknown
@@ -1195,9 +1182,7 @@ the daily full-public sweep, and high-risk release profiles. It aggregates
duration, failures, timeouts, current-inventory coverage, and targeted profile
ownership without copying stdout/stderr tails or repository-local paths.
-full-public workflow 还会把各 shard 回执聚合成一个紧凑健康产物。报告区分四种频率,
-而不是把每个 smoke 都变成 PR 必跑项:显式 PR 快速 smoke、catalog 选择的 canary、
-每日 full-public 全量,以及高风险 release profile。它会统计耗时、失败、超时、当前
+full-public workflow 还会把各 shard 回执聚合成一个紧凑健康产物。报告区分四种频率。它会统计耗时、失败、超时、当前
清单覆盖率和定向 profile owner,同时不会复制 stdout/stderr tail 或仓库本地路径。
```bash
@@ -1215,7 +1200,7 @@ test is valueless.
默认输出是有界的审阅摘要;只有显式诊断冷路径才使用 `--include-inventory`。内容完全
相同或直接嵌套执行只会成为审阅候选;名称相似、共同属于某个 profile,不足以证明两个
语义合同等价。健康审计不会自动删除或迁移 smoke。只有 daily 全量覆盖、没有定向
-profile 的条目表示 owner 待澄清,并不等于该测试没有价值。
+profile 的条目表示 owner 待澄清。
## Agent-Facing Output Budgets / Agent 输出预算
@@ -1228,7 +1213,7 @@ decision process below when changing a budget. Default agent-facing projection
changes remain subject to the existing owner review.
接口预算门会测量稳定命令场景,并比较 candidate 与 base,捕获意外膨胀、重复诊断
-以及重构后悄悄回到热路径的字段。预算保护有用且有界的决策,历史上限不是优化目标。
+以及重构后悄悄回到热路径的字段。预算保护有用且有界的决策。
解释新增或删除的语义字段,预算调整按下述流程判断;默认 agent-facing 投影变化
仍遵循既有的 owner review。
@@ -1275,7 +1260,7 @@ metrics, headroom and platform limits; the 40,000 fixture above stays unchanged.
副本引用该 owner,不同 channel 的规则仍内联。这恢复了默认投影此前省略的规则;
`--include-detail vision` 仍返回完整内联 audit。原有 40,000 字符 fixture 预算不变,
同一负载修复前/后为 30,697/33,205 字符,详情为 56,401 字符。这是 JSON fixture
-测量,不代表 token 成本或模型行为证据。
+测量。
完整 CLI 输出是另一负载:原 36 Todo/12 run vision 场景为有损 45,313/完整
48,418 字符;保留全部决策义务并核对受影响模式后,46,000 展示上限调至 50,000。
@@ -1305,8 +1290,7 @@ local-private; the workflow adds no profiler service or receipt gate.
- **Locate the cost before selecting an abstraction.** Separate caller repeats,
output/context expansion, process/bridge/serialization cost, shared semantic
work, and backend IO/verification/contention. A display filter does not reduce
- upstream work; a short response or fast isolated query does not establish a
- faster recovery loop. Name the real consumer and measure its useful outcome.
+ upstream work; Name the real consumer and measure its useful outcome.
- **Share contracts, qualify implementations.** Put common selection, bounded
reads and observation reuse at the existing consumer/typed owner boundary.
Preserve completeness, current authority, receipt replay and lease/CAS checks.
@@ -1337,15 +1321,13 @@ TS RFC 管语义 owner 与跨语言成本,shared-authority RFC 管后端容量
沿用现有任务、PR 证据和验收记录,不增加审批、回执或无关里程碑前置条件。
- **先定位成本。** 区分重复调用、输出与上下文展开、进程与序列化、公共语义计算、
- 后端 IO/校验/竞争。输出过滤不减少上游计算;单次查询变快不等于恢复闭环变快。
+ 后端 IO/校验/竞争。输出过滤不减少上游计算;
- **共用合同,分别验证实现。** 选择、有界读取和观测复用归现有调用方或 typed owner;
保留完整性、当前权限、回执重放及 lease/CAS。缓存失效、索引和历史布局可以因后端
而异,不能在 Python 复制权威,也不强造统一缓存。受影响后端遵循上文真实路径验证。
- **迁移是待验证的原因。** 尽量控制操作、版本、数据与历史规模、配置、并发;按影响
- 区分冷/热读、多存储交替、写入与恢复。没有受控前后对照就披露不确定性;晋升成功
- 不证明长程延迟、容量和恢复等价。
-- **验证实际目标。** 检索用独立标注、歧义/无命中和语言边界验证;开发小样本不代表
- 生产精度或任务成功率。运行时优化保留原失败负载和语义/规模检查,预算按下节处理。
+ 区分冷/热读、多存储交替、写入与恢复。没有受控前后对照就披露不确定性;
+- **验证实际目标。** 检索用独立标注、歧义/无命中和语言边界验证;运行时优化保留原失败负载和语义/规模检查,预算按下节处理。
- **区分缓解与闭环。** 写明消除了所属瓶颈,还是只减轻调用方影响;剩余真实缺口复用
已有后续任务并指明验收。提示词缩短不算后端验证,修复 PR 数量不算默认切换就绪。
@@ -1426,8 +1408,7 @@ that input. Retain the original over-budget observation and add the complete
CLI combination plus an oversized-route negative case. Prompt text, capability
flags, the visible Goal's 4,000-character host limit, existing JSON/body fixture
ceilings, execution authority and frozen qualification results remain unchanged.
-This corrects diagnostic coverage; it is not an output reduction or a claim of
-model compliance, runtime recovery or lower cost.
+This corrects diagnostic coverage.
薄提示原 4,500 字符展示预算未覆盖完整能力与显式 CLI 路由的组合;同一公开夹具
保留 320 字符 scope、五项能力和完整指令时为 4,851。仅将该展示预算校准为
@@ -1471,7 +1452,7 @@ performance criteria, and does not qualify a model by itself.
真实模型组合门的同一组三个 noisy fixture 现保留完整的 56 个 capability 候选及其
正文。仅按上述实测把该合成 fixture 的 pretty-JSON UTF-8 字节预算从 40,000 调整到
90,000;原超限失败保留。新增候选丢失/正文缩短的零模型调用负例,原选择、人工门禁、
-结算、重复次数、对照及生产硬边界不变;本次预算修正不等于真实模型通过。
+结算、重复次数、对照及生产硬边界不变;
This allowance is not a target architecture. A source-level attribution at
`d4980a0e9aa8acf8b847e2fec73d29454c23690d` reproduces those three output sizes.
@@ -1500,7 +1481,7 @@ explicit required-read contract; this design does not weaken or rewrite it.
blocked、binding 正文分别为 28,767、19,168、19,168 字节。16 个 binding 是带正文的
Todo 形状,与生产 owner 的 capability/owner/blocked-ID binding 不同;两个执行
fixture 的 selected Todo 不在 runnable 集合,human gate 没有 selected Todo。
-这些是压力成本,不是生产规模估计。保留原 fixture/失败,另用真实 producer、非重复
+保留原 fixture/失败,另用真实 producer、非重复
要求、有意义备选项及末尾约束验证选择与后续工作;计入全部批读/恢复成本。新必读契约
合格前,当前完整上下文 preflight 保持生效,不能靠删候选或首屏变小宣称收益。
@@ -1616,8 +1597,7 @@ Retain complete work context, canonical provenance and command routes, and
calibrate only this emitted-text regression ceiling to 42,000 (1,299 characters
above the native observation). There is no measured output reduction. Line,
per-Todo/fixed growth, semantic comparison and all other ceilings remain active.
-The original failure and the pending new native qualification remain distinct;
-this calibration is neither a model-cost saving nor a frozen performance pass.
+The original failure and the pending new native qualification remain distinct.
原生 Windows 同轮 base/head 均为 40,701 字符,原 40,000 超限失败保留。
先保留配对度量,再仅将该展示回归上限校准到 42,000;不删当前工作、来源或命令,
@@ -1625,8 +1605,7 @@ this calibration is neither a model-cost saving nor a frozen performance pass.
冻结实验通过;修改后的原生验证仍需独立读回。
Classify the limit by its owning contract before deciding how to repair a
-failure. This applies to output size/structure and latency regression budgets;
-it does not grant execution quota, spending, or provider authority.
+failure. This applies to output size/structure and latency regression budgets.
The native installed-profile smoke exposed duplicate settlement instructions
inside the visible Goal body. On identical long installation routes and the
@@ -1642,7 +1621,7 @@ failure; the installed-profile smoke and semantic assertions qualify the repair.
4,000 字符宿主硬边界、完整路由、当前合同、事实证据、恢复与停止条件均不变。
先根据所属合同判断上限的性质,再选择修复方式。这适用于输出尺寸、结构和延迟
-回归预算,不授予执行配额、费用额度或 provider 权限。
+回归预算。
| Limit / 上限 | Decision boundary / 决策边界 |
| --- | --- |
@@ -1660,7 +1639,7 @@ transport saving or permission to exceed a host limit.
Heartbeat 的正文回归计量先归一化已选择的 runtime、registry 和 active-state
完整路径及其 shell 引用形式,再处理 Goal id、父路径等子串;未声明路径仍计入。
原始正文 `char_count`、JSON/Markdown 输出预算与原生 Goal 宿主的 4,000 字符
-传输检查各自保留。归一化元数据不代表传输节省,也不豁免宿主限制。
+传输检查各自保留。
1. **Measure the same contract.** Record base/head revisions, workload, metric
and measurement boundary. Compact JSON characters, UTF-8 bytes, nested keys,
@@ -1712,8 +1691,7 @@ complete authoring bounds and parsed semantic-closeout arguments with the
original admitted contract; recovery specializes the completed Task's boundary.
Spend and settled
recovery keep their 2,000-character ceilings. This preserves useful guidance;
-it is neither an output reduction nor a change to any external host limit or
-frozen performance criterion. Candidate measurements must still pass.
+Candidate measurements must still pass.
辅助 Monitor 的恢复夹具用缩进 JSON 测量完整的原始 writeback 步骤,File 与 SQLite
均使用固定宽度的临时路由。发布基线均为 8,642 字符,原 7,500 字符回归上限的失败
@@ -1721,15 +1699,13 @@ frozen performance criterion. Candidate measurements must still pass.
判断、原始身份和命令。删除这些义务或给这段小型恢复指令另加引用都会改变消费
合同,因此只将该回归上限校准为 9,336,保留原 694 字符余量,并与最初准入合同
逐字段比较完整 authoring 约束与解析后的 semantic-closeout 命令参数;恢复步骤保留
-已完成 Task 所需的具体结算边界。spend 和 settled 恢复仍受 2,000 字符上限约束。这不代表输出
-缩小,不改变外部宿主硬限制或冻结性能标准;候选版仍须重新测量并通过检查。
+已完成 Task 所需的具体结算边界。spend 和 settled 恢复仍受 2,000 字符上限约束。候选版仍须重新测量并通过检查。
Native progressive-context qualification found an existing default-output
budget failure: immutable base `fb331f45c` and candidate `edbd56b14` both emit
25,836 JSON characters for `quota_should_run/multi_agent` with the unchanged
18-Todo, 3-Agent, 12-run fixture. Recursive comparison differs only in observation
-timestamps and the rollout event id. This is neither an incremental native-off
-regression nor evidence of a saving. Preserve the previous 25,500-ceiling failure;
+timestamps and the rollout event id. Preserve the previous 25,500-ceiling failure.
calibrate this one regression allowance to 26,500 (664 characters of headroom)
without dropping fields. Markdown, line, semantic, bootstrap duplication,
per-Todo/fixed growth and all other surface ceilings remain unchanged. This
@@ -1739,7 +1715,7 @@ criterion. Native-on material and recovery savings need separate qualification.
原生渐进上下文资格检查发现已有默认输出超限:不可变 base `fb331f45c` 与 candidate
`edbd56b14` 在相同 18 个 Todo、3 个 Agent、12 条运行记录夹具上,
`quota_should_run/multi_agent` 都为 25,836 JSON 字符;递归对比只有观察时间和
-rollout event id 不同。这不是 native-off 新增回归,也不是节省证据。保留旧 25,500
+rollout event id 不同。保留旧 25,500
阈值失败,只将这一回归预算校准为 26,500,留 664 字符余量,不删除字段。Markdown、
行数、语义、bootstrap 重复、每 Todo/固定增长及其他 surface 阈值不变;宿主硬限制、
授权执行配额和冻结实验标准均不变。Native-on 材料和恢复收益须单独验证。
@@ -1833,8 +1809,7 @@ Linux crowded/multi-Agent Turn envelopes measure 10,766 / 9,391 UTF-8 bytes;
plain envelope, transaction detail and multi-subagent measure
8,544 / 8,539 / 9,312. They still report `within_budget=false` and
`turn_envelope_budget_exceeded`; small Turn and blocking-user-gate remain
-within at 8,057 / 6,045. These warnings are not a green performance SLO or
-admission authority. This calibration grants no execution quota, spending or
+within at 8,057 / 6,045. This calibration grants no execution quota, spending or
provider permission and does not rewrite frozen experiment/promotion results.
本轮固定真实 main/候选和同一负载,逐条保留当前任务、读取时序、新鲜度、恢复、
@@ -1851,9 +1826,8 @@ provider permission and does not rewrite frozen experiment/promotion results.
需要调用方迁移和语义等价验证。详情优先使用有界摘要和可达冷路径。不能删身份、
完整性、安全或结算语义,不能只为过线缩字段名,也不为微小收益制造引用框架。
agent 读取的文字也是决策语义:逐条核对执行者、触发、时序、义务强度、证据来源、
- 范围限定、继续和停止条件。“继续前先 replan”不等于“replan”,“关联证据的路径”
- 不等于“路径”,“合理的范围内下一步”不等于“范围内工作”。字段、命令、枚举和
- 合法结果未变,不能证明指令等价。不能为字符上限损害有用语义;未证明无损压缩时,
+ 范围限定、继续和停止条件。字段、命令、枚举和
+ 合法结果未变。不能为字符上限损害有用语义;未证明无损压缩时,
优先基于证据调整回归预算。真实硬上限需要明确的无损调用方设计和读回,不能默删义务。
3. **选择并披露取舍。** 比较压缩、保持上限、合理扩容,也可组合使用。扩容需说明
保留信息的价值与成本、新旧上限、实测余量和预期波动或规模,不规定统一余量比例。
@@ -1918,6 +1892,12 @@ an accepted goal/contract, not a compression target. Instruction readback proves
what was delivered, not actual model comprehension or adoption. The result
checker enforces evidence structure and contradictions, not semantic truth.
+For installed skill prose, also inspect readiness consumers such as
+`doctor.installed_skill_summary`. Validate shipped skills in an external skill
+root and a copy missing a concrete permission requirement. The platform-neutral
+cases in `tests/test_skill_delivery_parity.py` cover this boundary even when
+native installer tests skip on the current host.
+
PR-review 的 `semantic_alignment` 通过既有 `validation_matrix` 和
`observable_semantics` 使用这些证据,不增加独立预算回执或审批门。结果校验器检查
证据结构和结论一致性;测量是否可信、取舍是否合理仍由评审判断。
@@ -1926,6 +1906,11 @@ PR-review 的 `semantic_alignment` 通过既有 `validation_matrix` 和
压缩指标不能授权。指令读回只证明交付了什么,不证明模型理解或采用;校验器检查
证据结构和矛盾,不自动判断语义真假。
+修改已安装技能文案时,还应检查 `doctor.installed_skill_summary` 等 readiness
+消费者。用外部技能目录中的发布技能,以及缺少具体权限要求的副本验证该边界。
+`tests/test_skill_delivery_parity.py` 的跨平台用例在原生安装测试因宿主不同而跳过时
+仍可执行。
+
## Decision Replay And Issue #2191 / 决策回放与 #2191
Issue #2191 is the reference pattern for a cross-layer control-plane
@@ -2128,14 +2113,13 @@ projected bound refresh and spend, and pass durable checkpoint, one-spend and
next-Turn readback. Readback must clear the original missing-baseline obligation;
a legitimate new successor requirement is allowed. Source alignment includes trigger kinds, accepted outcomes
and qualification scope; a successful ordinary `typed_progress_repeat` refresh
-cannot qualify this journey. The narrow semantic-action gate remains useful
-but does not prove full closeout. Run this focused journey with
+cannot qualify this journey. Run this focused journey with
`uv run --extra test python scripts/qualify-doubao-replan-semantic-action-live.py --required-vision --qualification-id `.
The complete required-vision journey has a 40-call bound; the narrow
single-semantic-action qualifier retains seven. The increased budget covers
evidence discovery, JSON authoring, refresh, settlement and bounded recovery,
including multiple field-validation corrections before a final spend;
-it does not authorize more effects or weaken the checkpoint/readback oracle.
+
Each receipt records `tool_call_limit` beside actual usage. Earlier seven- and sixteen-call
failures remain failures; the revised budget defines a new qualification, not
a retrospective pass. Limit exhaustion after refresh but before spend still
@@ -2173,8 +2157,7 @@ original Turn. Additional recovery reads consume the ordinary budget; they
grant no extra calls. The model must reassess the changed facts and author a
new decision before retrying. Draft authoring requires the same OS isolation
prerequisite as the full journey. Other actors retain their
-existing host and call limits. Earlier bounded-grammar and missing-decision failures remain failed
-qualifications and are not evidence of core semantic rejection.
+existing host and call limits.
The other turn cases remain
bounded packet-interpretation checks. Nine core-contract scenarios cover
onboarding, agent identity and goal selection, selected todo, peer identity
@@ -2263,8 +2246,7 @@ executable work 属于预期状态,不能误判为 projection gap。
Goal lifecycle on a disposable ledger project with two dependent Todos. It
reuses the shipped native Goal transport and current prompt, then checks an
independent acceptance oracle, completed Todos, unique bound spends, durable
-writeback readback, and terminal no-follow-up quota. This is not a benchmark
-score or evidence of universal model reliability.
+writeback readback, and terminal no-follow-up quota.
The Codex release arm requests the shipped bootstrap, not an injected private
work recipe. Deterministic regressions execute the saved CLI loader, change its
@@ -2304,8 +2286,7 @@ deadline is 1,200 seconds; this is a wall-clock ceiling, not a token budget.
但保留 `skipped` 标记;真实执行后失败不能冒充环境跳过。使用操作者显式选择的 API
模型、地址与密钥,不导入日常 Codex 配置、登录或会话,不修改活跃 Goal/automation。
任务、registry、runtime 与 Git worktree
-在一次性目录内;沙箱允许该目录及本地 TS worker 所需的网络能力,
-这不是网络隔离,任务不授权外部操作。回归脚本不采集或上传原始对话/工具日志,
+在一次性目录内;沙箱允许该目录及本地 TS worker 所需的网络能力。回归脚本不采集或上传原始对话/工具日志,
公开结果仅包含状态、计数和错误类别;Codex 会话仅留在一次性隔离目录内。
两个 runner 均从允许列表创建环境并隔离 HOME、配置和缓存;不透传其他 token、
认证 socket、shell 启动变量或原始 ARK_API_KEY。Codex 工具 shell 从空环境注入必要
@@ -2327,15 +2308,13 @@ decisions remain outside model input. All attempts must pass; no answer
correction or retry-until-pass is used. Ordinary pytest only checks the probe
and negative oracles with scripted responses, without provider calls.
-This is a synthetic decision-level probe using current generated prompts,
-not proof of tool execution, host scheduling, upgrade delivery or full-Goal
-completion. Keep the Codex/Claude live Goal arms and real CLI/MCP/SQLite tests
+This is a synthetic decision-level probe using current generated prompts. Keep the Codex/Claude live Goal arms and real CLI/MCP/SQLite tests
as separate evidence. Only hashes and pass/fail receipts are emitted, not raw
prompts/responses. Model transport failures fail qualification rather than
becoming environment skips.
仅发布前显式执行,普通 CI 不调用模型。检查静默不等于空转、等待不能擅自执行、
-vision replan 未关闭时不能提前结束 Goal;这不是完整 Claude/Codex 行为验收的替代。
+vision replan 未关闭时不能提前结束 Goal;
```bash
# No provider call by default. Explicit release opt-in uses ARK_API_KEY from the environment.
@@ -2371,7 +2350,7 @@ Before calling a changed host surface release-qualified, distinguish:
普通 CI 只跑确定性规则、真实 CLI/MCP 和故障注入;模型执行仍仅 release 前显式启用。
环境缺失可 skip 且退出成功,但最终版本没有完整的真实 host 结果时,不得写成
-“产品级发布验证通过”。单次成功也不是模型可靠性或长程调度 soak 的证明。
+“产品级发布验证通过”。
The real delivery regression covers ordinary Todo acceptance before internal
writeback/spend, existing-successor linking, and receipt-backed terminal closure.
@@ -2433,8 +2412,7 @@ decision basis. Judge the returned basis, then submit `agent_vision=...` or
replaced receipt requires another read and a new judgment; a lost response
requires the exact same receipt and decision, without reading again.
It uses the original host Turn and the same writeback command constructor,
-delegating to the existing typed checkpoint recovery. It neither repeats Todo
-completion nor spends again. Exact replay is idempotent; a conflicting committed
+delegating to the existing typed checkpoint recovery. Exact replay is idempotent; a conflicting committed
decision or a later superseding vision is rejected. It does not change Next
Action or erase other work, gates, or permissions. A genuinely new replan follows
the current interaction contract under a fresh admitted binding, not an edit to
@@ -2455,7 +2433,7 @@ MCP 可随完成操作携带 vision 判断,也可用 `review_task_vision` 在
复用 TS 的既有恢复规则,不新增结算引擎、不重扣额度;已提交的判断不能偷偷改写。
格式和预算预检在 Todo 完成前拒绝非法输入;若旧宿主已部分完成,则修正未提交的
vision 并重试原 `complete_task`,不能用仅补 checkpoint 的操作替代未完成结算。
-“checkpoint 满足”不等于“Goal 完成”,`vision_closed` 只结束阶段,真实缺口仍须规划。
+
外层任务只描述业务验收,LoopX 协议由宿主内层指令和工具承接。
## Exact Release Commit Gate / 精确发布 Commit 门
diff --git a/docs/guides/agent-upgrade.md b/docs/guides/agent-upgrade.md
index 21f021d897..f4fce8f6b8 100644
--- a/docs/guides/agent-upgrade.md
+++ b/docs/guides/agent-upgrade.md
@@ -46,8 +46,7 @@ If an upgrade primitive fails, preserve the source and name that specific gap.
## Reuse the owner for the observed state
Inspect the actual installation's `--help` before executing commands. These
-operations have different owners; a successful package update does not prove
-that existing Goal data have been upgraded.
+operations have different owners.
| Observed state | Existing entry | Required readback |
| --- | --- | --- |
@@ -56,7 +55,7 @@ that existing Goal data have been upgraded.
| Existing Goal still uses Markdown authority | `coordination-shadow inspect-source`, `prepare-import`, `apply-import` | Full source records and settled history imported into the reviewed provider; original paths remain. Recover the same import with `recover-import`. |
| Canonical Goal retains historical `legacy` policy | `handoff-mode plan-migration`, `handoff-mode migrate` | Verified backup, preserved assignments and an explicit supported policy. Recover the same plan after a lost response. |
-An expired lease is not proof that its writer stopped. `--writers-stopped`
+`--writers-stopped`
attests a fact already established through the owning Host; it does not stop
one. An already current canonical Goal needs no import. Setting new-Goal
defaults does not upgrade existing Goals. Storage and ownership policy remain
diff --git a/docs/guides/codex-app-autonomous-goal-experience.md b/docs/guides/codex-app-autonomous-goal-experience.md
index 7231463a2a..6bc4019628 100644
--- a/docs/guides/codex-app-autonomous-goal-experience.md
+++ b/docs/guides/codex-app-autonomous-goal-experience.md
@@ -12,7 +12,7 @@ $loopx 任务
→ Dashboard 展示进度、等待和完成状态
```
-这不是让一个模型会话无限运行。每次 Heartbeat 都先读取当前 LoopX
+每次 Heartbeat 都先读取当前 LoopX
状态;只有配额、Todo、能力和 Gate 都允许时,Codex Agent 才会执行一个
有边界的工作片段。
@@ -28,7 +28,7 @@ $loopx 任务
## 开始前
-适用范围是 **Codex App**,不是 Codex CLI、Codex App over SSH 或其他宿主。
+适用范围是 **Codex App**。
这些宿主的循环驱动不同;本路径依赖 Codex App 提供的
`automation_update`。
@@ -93,8 +93,7 @@ $loopx --fine-grained 在当前试验仓库中完成一份 LoopX 自动续跑体
- 此时 **不应** 有自动化已启动或业务文件已修改的结论。
`$loopx` 是 Codex 中的显式 LoopX skill 入口。只运行
-`loopx start-goal --guided` 同样会得到启动方案,但它本身只是引导预览,
-不等于 Heartbeat 已安装。
+`loopx start-goal --guided` 同样会得到启动方案,但它本身只是引导预览。
## 第 3 步:确认受控启动并安装 Heartbeat
@@ -116,8 +115,7 @@ Heartbeat 后,回读 Goal、Agent、自动化绑定和 quota should-run,不
4. Codex App 用 `automation_update` 保存其中的
`LoopX managed heartbeat bootstrap v2` `task_body`;
5. 新 Heartbeat 建议从 3 分钟开始,并回读其 Goal、Agent、任务绑定和调度;
-6. 后续唤醒加载当前 thin contract,而不是把一份旧的 thin、compact 或 full
- 执行正文永久保存为自动化提示词。
+6. 后续唤醒加载当前 thin contract。
这一步才是“启动 Codex Agent 自动续跑”的边界。若会话没有
`automation_update`,正确结果是一个可粘贴的宿主激活 Gate;不要手改数据库、
@@ -148,7 +146,7 @@ loopx quota should-run \
- `quota should-run` 返回当前机器契约,包括 `should_run`、`waiting_on`、
下一条工作通道和 `scheduler_hint`;
- `should_run=true` 表示下一次 Heartbeat 可以尝试有边界的工作;
-- `should_run=false` 不代表故障。先依据 `waiting_on`、Gate、缺失能力或配额
+先依据 `waiting_on`、Gate、缺失能力或配额
原因处理,不要为了制造活动而绕过限制。
这两个命令用于观察。真正的自动 Turn 由已安装的 Codex App Heartbeat 进入,
@@ -171,8 +169,7 @@ loopx dashboard --global-registry --goal-id "$GOAL_ID"
- Tasks 展示“待确认”“待执行 / 进行中”“定时与持续”和“已完成”四类工作;
- Goal 详情和 Run 抽屉展示公开安全的状态、进度、证据、产出和下一步。
-Dashboard 读取 LoopX 状态并轮询刷新。它不是 Heartbeat 的执行器:关闭浏览器
-不会停止已安装的 Codex App 自动化,打开浏览器也不会额外触发一次工作。
+Dashboard 读取 LoopX 状态并轮询刷新。
## 第 6 步:观察首次自动唤醒
diff --git a/docs/guides/codex-multi-app-best-practices.zh-CN.md b/docs/guides/codex-multi-app-best-practices.zh-CN.md
index ab0a347734..b974b0adc0 100644
--- a/docs/guides/codex-multi-app-best-practices.zh-CN.md
+++ b/docs/guides/codex-multi-app-best-practices.zh-CN.md
@@ -48,11 +48,11 @@ GPT 实例除 `CODEX_HOME=$HOME/.codex-gpt` 与 `--user-data-dir=.../Codex GPT`
- 克隆发 Apple Events 报 `Sender process is not authenticated`(错误 `-10000`),App 每 ~0.4 秒重试一次、每次泄漏一个 `SkyComputerUseService` 子进程,几分钟内打爆进程表。
- 症状:zombie 上千、load average 400+、CLI / 测试全部 `fork: Resource temporarily unavailable`。
-结论:**该授权无法通过系统设置或 TCC 授权解决**(不是权限 checkbox,是发送者签名身份校验);需要 Computer Use 时请用官方签名实例。
+需要 Computer Use 时请用官方签名实例。
### 2. 不要用 `launchctl submit` 做「延迟重启」
-`launchctl submit -l