@jsonstudio/appsdk-linux-x64-gnu 0.0.0-stage → 0.1.15

package/skills/appsdk-project-governance/references/development-debug.md

@@ -0,0 +1,86 @@
+# Development and Debug
+
+## Feature or new project
+
+When persistent Guidance is selected, project the task-specific intake:
+
+```bash
+appsdk guide init --task <task-id> --mode develop --module <module-id>
+```
+
+Read the returned AGENTS and Skill sources, invoke the suggested Skills, and ask
+only unresolved questions. A PlanProposal is required only for the selected
+Guidance workflow. Otherwise establish the same goal/scope directly and proceed.
+
+Before implementation, bind the project context:
+
+```text
+requirements + acceptance + non-goals
+-> declared function owner + allowed/forbidden paths
+-> declared verification gates + prior records
+-> proportionate architecture and detailed design
+```
+
+Architecture and detailed design are required for a new project or meaningful
+cross-module or semantic change. A local change may use the existing design and
+use it directly. Within a selected Guidance workflow, use its declared bypass.
+
+Then:
+
+```text
+latest origin/main
+-> clean owner worktree
+-> minimal implementation
+-> candidate commit
+-> verification/review/delivery
+-> latest-main integration
+-> remote receipt
+-> lifecycle close
+-> worktree/claim cleanup
+```
+
+Candidate commit binds tree/artifact/evidence. It is not a delivery commit and
+does not authorize merge.
+
+Before adding behavior, perform an ablation check: confirm that the behavior is
+necessary, no declared owner already provides it, and common semantics can
+reuse an existing shared function. Preserve a fixed lifecycle skeleton only
+when the project declares one. Choose direct code or configuration by actual
+complexity, not by a universal preference. Missing capability fails or skips with a
+reason. Control/configuration truth belongs only in declared typed control
+resources, error chains, or project configuration sources, never business
+payloads, metadata, debug logs, or implicit context.
+
+## Debug
+
+When persistent Guidance is selected, start with:
+
+```bash
+appsdk guide init --task <task-id> --mode debug --module <module-id>
+```
+
+Use the projected questions to bind the real failing sample and experiment
+contract before writing the debug PlanProposal.
+
+Use one hypothesis per round:
+
+```text
+read AGENTS + declared maps + prior notes/records
+-> append observations, one hypothesis, and evidence to run notes
+-> same-input reproduction when feasible
+-> confirmation/falsification signals + first semantic divergence
+-> forward and reversal intervention when feasible
+-> unique-owner fix + proportionate regression
+-> mapped gates + old-input replay when runtime-impacting
+```
+
+Final error is not automatically root cause. Grep hit is not evidence. Do not
+patch output layers, add fallback, or modify multiple owners to make one test
+green.
+
+Before merge, review maps, module boundary, owner, payload/control separation,
+configured operations, registered hooks, declared gates, ablation, shared
+function reuse, affected tests, and the latest-main integrated tree. A violation
+introduced or modified by the candidate blocks review. An untouched historical
+violation is a recommendation unless it affects the changed scope, safety,
+ownership, evidence truth, or required delivery.

package/skills/appsdk-project-governance/references/goal-prompt.md

@@ -0,0 +1,69 @@
+# Goal Prompt Generation
+
+Use only when the user asks for a goal prompt. An ordinary development/debug
+request does not require generating a prompt or writing a separate plan file.
+For a requested prompt, clarify material unknowns:
+
+1. Restate the objective in one sentence.
+2. List acceptance criteria.
+3. List non-goals and assumptions.
+4. Identify ambiguity and ask only material questions.
+5. Wait for confirmation when scope, risk, permission, or irreversible behavior is unclear.
+6. Write `docs/goals/<feature-name>-plan.md` before emitting the prompt.
+
+Never put a token, time, context, or turn budget in the plan or `/goal` prompt.
+Do not emit fields such as `token_budget`, budget seconds, context limits, or
+round limits. Completion is determined only by the plan's acceptance criteria
+and evidence.
+
+For an MVP→M1 migration or closeout, the plan is the single implementation
+source and must additionally bind:
+
+- the current MVP baseline and the intended M1 target;
+- the owning endpoint/project scope, allowed and forbidden paths, and the
+  authorized master/worker boundaries;
+- the legacy control-plane inventory, retained evidence, chosen preserve/reset
+  route, and exact destructive authorization (if any);
+- the five Loop parts (`Trigger`, `Work`, `Gate`, `State`, `Stop`) and the
+  per-round order `Discover → Hand off → Verify → Persist → Schedule`;
+- the AppSDK source-repository versus managed-project boundary, Codex TUI
+  identity and route evidence, two-way replay, and explicit failure/unknown
+  handling;
+- exact candidate, merge, install, daemon-restart, and deployed replay gates.
+
+Use the [AppSDK migration Skill](../../appsdk-migration/SKILL.md) for the complete
+inspect/snapshot/migrate-or-reset/context-reconcile/restart/verify procedure. Do not copy
+that state machine into the prompt or into this reference. A prompt cannot
+register a goal or grant a role: Desktop never runs `appsdk goal subscribe`;
+only the authorized live TUI/master endpoint may register the existing plan.
+If the plan is absent, unconfirmed, or not admitted, stop before emitting a
+usable execution prompt. A periodic interval is a scheduling choice, not a
+ten-second liveness probe or permission to retry a blocked command.
+
+Use this compact output:
+
+```text
+/goal
+目标：<one-sentence objective>
+
+说明：本任务不需要再写新的提示词，直接按实现文档执行。
+
+实现文档：
+docs/goals/<feature-name>-plan.md
+
+执行规范：
+- 先查项目合同、owner、scope 和真源。
+- 只在允许路径修改；禁止 fallback、silent strip、旁路和无关改动。
+- 目标未 confirmed/admitted 时停止实现。
+- 不声明 token、时间、上下文或轮次预算；按完成条件和证据收口。
+
+验证：
+- 运行定向测试、build/compile、verify 和要求的 review gate。
+- 无证据不宣称完成。
+
+完成标准：
+- 实现计划中的验收标准全部满足。
+- 记录、artifact、scope 和 review 结果一致。
+```
+
+The prompt is the final execution task. Do not create another prompt for the same task.

package/skills/appsdk-project-governance/references/init-prompts.md

@@ -0,0 +1,212 @@
+# AppSDK + Collab: one query, one binding
+
+Current client: Codex only. The binding is the Codex sessionID.
+
+## State ownership
+
+Global truth:
+
+```text
+~/.appsdk/projects.jsonl
+~/.appsdk/runtimes.jsonl
+~/.appsdk/communication.jsonl
+~/.collab/server.sock
+~/.collab/events.jsonl
+~/.collab/log.txt
+```
+
+Project-local `.appsdk/`, `.appsdk-control/`, and `.agent-collab/` are not the
+global truth. `.appsdk/` is the committed project contract/maps/records;
+`.appsdk-control/` is ignored local run/cache state; `.agent-collab/` is the
+project registration/reducer input. Handle them only through
+the AppSDK reset or Collab migration/reset owner. Do not inspect or edit them
+to decide whether the peer is registered.
+
+## All state
+
+Run one command:
+
+```sh
+collab context
+```
+
+`collab context` returns identity, liveness, tasks, inbox, `next_actions`,
+master/authority state, `role_brief`, and truth. Registration returns the brief
+effective at registration; `collab context` projects the current brief, and
+promotion or delegation returns the replacement brief. That output is the
+truth. `registered: true` ends bootstrap. If the snapshot returns
+`required_fields`, supply only those real facts once:
+
+```sh
+collab context --provide '<JSON>'
+```
+
+The supplement may contain only requested `session_id`, `thread_id`,
+`endpoint`, or `namespace` facts; it never supplies a worker, approval, token,
+route, or binding. The supplement invocation returns the resulting snapshot.
+Do not choose a worker or run another identity command. If context returns an
+explicit daemon DOWN or runtime error, preserve the exact error and stop;
+daemon lifecycle maintenance is human-authorized. Do not inspect local
+environment/control paths or run any other exploratory command. Registration
+and wake use the internal Codex App Server native thread.
+
+Ordinary AppSDK project initialization runs only in the canonical project main
+checkout. Agent identity bootstrap is `collab context`; it may run from the
+project or worktree, and the daemon resolves the canonical route. A Git
+worktree contains tracked `.appsdk/` files but does not inherit ignored
+`.agent-collab/` or `.appsdk-control/` state. The separate authorized AppSDK
+`--fresh --discard-legacy` reset may run from its clean non-main owner worktree
+as specified below. Inside a worktree, the same Codex sessionID/thread remains
+the same peer. Run `collab context` directly there; it reports the inherited
+identity, liveness, tasks, inbox, `next_actions`, and master/authority state.
+Never register the worktree as a second peer, promote yourself, or create a
+second route.
+
+## If required facts are missing
+
+`collab context` can return `registered: false`, `identity: null`, and
+`required_fields`. Supply only the real requested facts once with
+`collab context --provide '<JSON>'`. The supplement may contain only requested
+`session_id`, `thread_id`, `endpoint`, or `namespace` facts; it never supplies
+a worker, approval, token, route, or binding. The daemon owns identity
+creation, selection, restoration, update, registration, route publication, and
+lease restoration. Do not run AppSDK or Collab initialization to repair
+identity, and do not inspect routes or worker state to guess a binding.
+
+## Master (after user approval for the exact project + peer)
+
+```sh
+cd /abs/path/project
+collab context                  # verify sessionID binding and role
+# if required_fields are present, provide only those facts once
+# only when the context snapshot has no live master and the user approved
+# this exact peer:
+collab master promote --approval "<user approval text>"
+collab context
+# only after the plan exists and long-horizon work is approved:
+appsdk goal subscribe --goal docs/goals/<feature>-plan.md --interval 10m
+appsdk goal status --json       # active/observed/collab_subscribed
+```
+
+The master then owns orchestration:
+
+1. Query `collab context` once. It must show the identity, liveness, tasks,
+   inbox, `next_actions`, `role_brief`, and master/authority state.
+2. Split the confirmed goal by dependency and unique write scope. Dispatch
+   through `collab subagent dispatch` or `appsdk subagent send`; every
+   assignment needs done-iff, artifacts, forbidden paths, exact tests, and
+   evidence location.
+3. Before execution or dispatch, run `appsdk bug intake --input <json>` and
+   bind the returned `issue_id`; read-only conversation skips this path.
+4. Keep workers saturated from the approved task graph, then from
+   `appsdk bug list --status open --json` in `P0 > P1 > P2` order.
+5. Own blockers, re-dispatch or auditable force-close stuck tasks, integrate
+   reviewed commits on latest main, and keep source/review/merge/install/
+   restart/live-replay evidence separate.
+6. Remove only resources created by this round. Preserve other peers'
+   worktrees, processes, and evidence.
+
+Stop normal setup here. Do not run operator diagnostics, read `routes.jsonl`,
+inspect processes, or list `.agent-collab/`. If context explicitly reports
+daemon DOWN or a runtime error, preserve the exact error and stop; daemon
+lifecycle maintenance is human-authorized.
+
+## Long-horizon master initialization and timer proof
+
+The master creates the plan file before registering the timer:
+
+```sh
+appsdk goal subscribe --goal docs/goals/<feature>-plan.md --interval 10m
+appsdk goal status --json
+appsdk longhorizon show --json
+```
+
+`appsdk goal status --json` must report `active: true`,
+`desired: subscribed`, `observed: subscribed`, `collab_subscribed: true`, a
+non-null `subscription_id`, and `error: null`. Command output alone is not
+timer proof. Run one short-interval live replay and record the armed
+subscription, fired deadline notification, and consumed result. The current
+implementation is a one-shot deadline; rearm it after consumption, expiry, or
+a Collab restart.
+
+## Upstream AppSDK bug report
+
+When a project hits a defect in AppSDK itself, do not patch around it or hide
+it in project-local state:
+
+```sh
+appsdk bug list -q "<symptom>" --json --upstream
+appsdk bug new --upstream -t "[SDK Bug] <symptom>" -m "<reproduction, expected, observed, version, commit, logs>" -l "P0,appsdk"
+appsdk bug show <id> --json --upstream
+```
+
+Include the source commit, binary version/hash, exact command, first failing
+layer, and whether the same path fails from a clean project. The upstream bug
+is a report and evidence record; it is not proof that the local delivery
+passed.
+
+`--upstream` is the explicit git-bug upstream route. The report must use the
+actual symptom, reproduction, expected/observed result, version/commit,
+and relevant logs; do not turn it into a local project bug or a fallback
+workaround.
+
+## Ordinary peer (project already has .appsdk/project.json and a live master)
+
+```sh
+cd /abs/path/project
+collab context
+# if required_fields are present, provide only those facts once
+```
+
+If context reports `role=master`, stop and report the conflict to the master;
+do not promote yourself and do not start a second daemon.
+
+Read master/authority state from the same context snapshot. A live master
+exists iff the returned `master` is an object with `endpoint_live=true`.
+`master: null` means no live master is recorded; a `master` object with
+`endpoint_live=false` is a recorded-but-dead identity and is not a live master.
+A worktree normally has no local `.agent-collab/`; that does not mean the peer
+is unregistered or that no master exists. A failed `collab context`, including
+`token mismatch`, is a registration problem, not evidence of no master. If it
+fails, preserve the exact error. Report the registration error to the live
+master only when the snapshot shows `endpoint_live=true`; when no live master
+exists, report it to the explicitly authorized migration/reset owner or the
+user and stop identity repair. Do not infer "no master", copy/edit identity
+state, reset, or promote yourself from the worktree.
+
+For an explicitly authorized clean epoch, the reset owners are separate. The
+AppSDK line is a reset/reinitialize operation, not ordinary initialization:
+
+```sh
+# AppSDK-owned project control plane, from a clean non-main owner worktree
+appsdk init <project> --fresh --discard-legacy
+
+# Collab-owned project control plane, during a controlled maintenance window
+collab down
+collab reset --project --discard-legacy --approval "<user authorization>"
+collab up
+collab context
+```
+
+Neither reset removes the other owner's state or proves delivery, review,
+install, restart, or live communication.
+
+## Identity and route reconciliation
+
+Identity creation, selection, restoration, update, route publication,
+registration, and lease restoration belong to the daemon. `collab context` and
+its one factual supplement are the only agent bootstrap. Do not copy tokens,
+edit identity state, or run separate route/status discovery for repair. If
+context explicitly reports daemon DOWN or a runtime error, preserve the exact
+error and stop.
+
+## Stale daemon, socket, or lock
+
+`~/.collab/server.sock`, `server.pid`, and `daemon.lock` are host-owned runtime
+objects. If `collab context` explicitly reports daemon DOWN or a runtime error,
+preserve the exact output and stop. Starting, stopping, or restarting the host
+daemon is human-authorized maintenance. An authorized human operator may use
+the official `collab down` / `collab up` lifecycle when a maintenance window is
+approved. Never diagnose identity by chaining status commands, remove lock or
+socket files by hand, use broad process-kill commands, or start a project-local
+daemon.

package/skills/appsdk-project-governance/references/process-control-harness.md

@@ -0,0 +1,162 @@
+# Development Process Control Harness
+
+This reference applies only when persistent Guidance is selected. `advisory`
+and `warning` never require setup, a plan or workflow close for independent
+development. Quality admission remains in canonical AppSDK gates. A missing
+optional setup returns `guide_flow_required: false`; do not start a setup detour.
+
+## Functions
+
+```text
+rule compiler      declared sources -> deterministic rule context
+plan controller    PlanProposal -> PlanRecord/PlanRevisionRecord
+execution ledger   step result -> append-only StepExecutionRecord
+state projector    lifecycle + plan + events -> readiness/blocker/next
+lifecycle bridge   domain node -> canonical AppSDK command/gate
+closeout projector final state -> gaps/cleanup/memory candidates
+```
+
+Harness does not call a model, produce project evidence, mutate lifecycle truth,
+or write memory automatically.
+
+## Tour and ordered review
+
+Use `appsdk guide tour --task <id> --mode <domain>` to inspect the generated
+workflow and let a human choose an adjacent path. Persist that choice with a
+TourProposal input when needed. Submit `appsdk guide review` in two stages:
+`node_review` checks and accepts node content first; only after every selected
+node has an accepted revision may `flow_review` update edges, order, or rules.
+The accepted flow patch retains node revision IDs and stays staged until the
+declared source is explicitly updated and compiled.
+
+## Start
+
+```bash
+appsdk guide status --task <task-id>
+appsdk guide init --task <task-id> --mode develop --module <module-id>
+appsdk guide develop --task <task-id> --module <module-id>
+```
+
+If status returns `GUIDANCE_SETUP_REQUIRED`, do not call compile yet:
+
+```bash
+appsdk guide init --task guidance-setup --mode bootstrap --module <module-id>
+```
+
+Read the returned candidate sources, produce the requested
+`GuidanceSetupProposal`, reuse session authorization that already covers a
+difference, and obtain explicit approval only for uncovered changes. The Agent
+then updates project-owned human and machine rule sources in a clean owner
+worktree, declares them in `.appsdk/project.json`, and runs `appsdk guide
+compile` plus `appsdk verify`. If status is only `GUIDANCE_NOT_COMPILED`,
+approved sources are already declared and compile is the next command.
+
+After an AppSDK update, or for an explicit rules refresh, a configured project
+uses the same read-only bootstrap intake:
+
+```bash
+appsdk init
+appsdk guide init --task guidance-upgrade --mode bootstrap --module <module-id>
+```
+
+Read current project sources before the returned standard template reference.
+Read actual test commands and CI/hook entrypoints as well as the rules. The
+resulting `template_upgrade_review` proposal may recommend changes, retain
+project rules, or decline template items. Record owner, action, basis, retained
+safeguard, and entrypoint impact for each difference; reuse session
+authorization that already covers a difference and ask only for uncovered
+changes. It does not write state or activate the template. Guidance is optional:
+without it, apply the same authorized audit and CI/hook changes without
+compile. Repeated init or unrelated version changes do not trigger a
+whole-project audit. Apply authorized differences in a clean owner worktree,
+then compile and verify when Guidance is selected.
+
+Use `--mode debug` for a bug, regression, or incident. Use another declared
+domain when appropriate. `guide init` is read-only and returns:
+
+- declared AGENTS and local Skill paths to read in precedence order;
+- unresolved develop/debug questions to ask the user;
+- exact `$skill-id` suggestions for declared local Skills;
+- missing commands and the next `appsdk guide` command sequence.
+
+Ask only questions still unresolved after reading the returned sources and the
+current user request. Then run the projected domain command and write the
+PlanProposal. `appsdk guide --help` lists the full command surface.
+
+`GuidanceSetupProposal` is project-level and user-approved. `PlanProposal` is
+task-level and stored in local control state. Never promote a task plan into a
+project Skill automatically.
+
+If status returns `MODULE_PATH_MISSING`, treat it as a project module-binding
+error. The named module owner updates that module's `owned_paths` or
+`contract_paths` to real project paths in `.appsdk/project.json`, recompiles
+guidance, and verifies. Do not classify it as a missing global package, Collab
+failure, or reason to wait for an external AppSDK owner.
+
+## PlanProposal
+
+```json
+{
+  "schema_version": 1,
+  "mode": "develop",
+  "goal_id": "goal-id",
+  "task_id": "task-id",
+  "module_id": "module-id",
+  "objective": "bounded objective",
+  "scope_paths": ["declared/module/path/**"],
+  "steps": [{
+    "step_id": "step-1",
+    "node_id": "requirements",
+    "action": "concrete action",
+    "owner": "module-id",
+    "expected_evidence": ["requirements"]
+  }]
+}
+```
+
+Do not provide `current_node`, `next_transition`, source hashes, scope hash, or
+rule-context hash. Harness derives them.
+
+```bash
+appsdk guide plan --task <task-id> --input plan.json
+```
+
+This is the first task-state write. It creates the active PlanRecord under
+`.appsdk-control/guidance/<task-id>/plan.json`; initialization does not create a
+second intake truth.
+
+## Update
+
+```json
+{
+  "schema_version": 1,
+  "event_id": "stable-unique-id",
+  "step_id": "step-1",
+  "result": "pass",
+  "observations": ["observed fact"],
+  "evidence": ["evidence-id"]
+}
+```
+
+```bash
+appsdk guide update --task <task-id> --input result.json
+appsdk guide next --task <task-id>
+```
+
+Same event ID and content is idempotent. Same ID with different content fails.
+`pass` with required but absent evidence fails. Only projected step may update.
+
+## Revision
+
+Resubmit PlanProposal with `revision_reason` when evidence, blocker, hypothesis,
+scope, owner, source, environment, rules, contracts, gates, or dependencies
+change. Old plan/events remain append-only. Never edit control files by hand.
+
+## Close
+
+```bash
+appsdk guide close --task <task-id>
+```
+
+Read `workflow_complete` and `appsdk_lifecycle_complete` separately. Apply
+memory candidates only through a separate reviewed change.

package/skills/appsdk-project-governance/references/review-delivery.md

@@ -0,0 +1,127 @@
+# Review and Delivery
+
+Apply this runtime lifecycle when runtime delivery is in scope. Documentation
+and rule edits use targeted checks; they do not invent a runtime deployment,
+Active artifact or freeze ceremony.
+
+## Authoritative requirement review packet
+
+Every design or architecture review that consumes project requirements uses
+[authoritative-review-template.md](authoritative-review-template.md). The
+dispatch must provide or clearly reference:
+
+- the project's authoritative requirement source, owner, exact read path, and
+  effective version;
+- the user original text, acceptance criteria, applicable scope, and any
+  explicit user change instruction with its prior version;
+- the exact candidate, base, review stage, allowed/forbidden paths, and current
+  stage evidence; and
+- the existing AppSDK EvidenceRecord and ReviewRecord references and the
+  backend-supplied review output schema.
+
+The executing agent fills only observed project facts and evidence references.
+It must not replace the source with a plan or author summary, edit the template
+for one task, or create an authorization. The independent reviewer reads the
+source and current version, compares the prior version when a change is
+claimed, and records each applicable item-to-design, item-to-implementation,
+and item-to-evidence mapping in the existing backend fields. Missing required
+sources, stale versions, unauthorized requirement changes, reduced acceptance,
+and candidate/scope mismatches block the review. Do not create a second review
+schema or a second requirement store.
+
+## Candidate to review
+
+```text
+candidate commit/tree/scope
+-> development whitebox
+-> exact artifact build
+-> install receipt when required
+-> restart receipt when required
+-> deployed public-entrypoint blackbox
+-> PreReviewValidationRecord
+-> appsdk verify --review-admission
+-> selected architecture review PASS
+```
+
+Review tool follows user choice; otherwise use configured default. Review is
+read-only and bound to exact candidate, scope, maps, artifact, and evidence.
+
+Required service operations come from module `deployment_operations`:
+`["install", "restart"]`, `["install"]`, `["restart"]`, or `[]`. An omitted
+field preserves the legacy install/restart requirement. The declaration is
+artifact-bound; changing it invalidates existing validation. Every supplied
+receipt is checked even when optional. Public-entrypoint blackbox and candidate,
+artifact, environment and producer identity remain required. The legacy
+`deployed_blackbox` label includes a library/CLI artifact's real consumer entry;
+mock or source-only checks cannot stand in for that artifact.
+
+Changed-scope architecture review must verify:
+
+- control/configuration truth uses declared typed control resources, error
+  chains, or project configuration sources and never business payloads,
+  metadata, debug logs, or implicit context;
+- each semantic behavior has one owner and one implementation, with no fallback
+  or temporary bypass;
+- a project-declared lifecycle skeleton preserves its owning boundaries;
+- additions passed an ablation check and common semantics use one shared
+  function;
+- missing operators, hooks, or gates fail or skip explicitly and never mock
+  success.
+
+Concrete quality, safety, contract or material structural regressions block.
+Optional simplification and design preferences are advisory. Untouched
+historical violations are reported as recommendations and do not block unless
+they affect changed scope, safety, ownership, evidence truth, or required
+delivery.
+
+Any source, test, build config, environment, artifact, scope, owner, or required
+rule change invalidates affected evidence. Refresh only affected evidence;
+revise the plan only when goal, scope, acceptance, key approach, or dependencies
+materially change. Follow the host contract for review triggers and finding
+re-checks; internal progress does not dispatch another review.
+
+## Review to mainline
+
+```text
+verify evidence freshness; reuse unchanged candidate evidence
+-> fetch latest origin/main
+-> exact integration build/test
+-> protected merge/push
+-> remote main receipt
+```
+
+Conflict returns to owner worktree. Do not resolve inside a serial merge queue
+and keep stale review evidence.
+
+EffectivenessRecord can reference pre-review candidate interventions and the
+validated blackbox when input hashes, artifact and candidate identity match
+and evidence has not expired. No mandatory rerun just because review finished.
+Environment or dependency/configuration changes require affected evidence to
+be refreshed. The full lifecycle still validates the current artifact and
+pre-review graph before accepting reused effectiveness.
+
+## Promotion and freeze
+
+```text
+RegressionReport on merged source
+-> appsdk compile
+-> publish immutable Active
+-> archive source/contracts/artifact in Protected
+-> FreezeRecord
+-> appsdk verify
+```
+
+Merge alone is not lifecycle completion. Active/Protected are immutable; use
+canonical version/open/rehydrate flows instead of manual edits or copies.
+
+## Cleanup
+
+Resource close is separate from engineering delivery. Retain an owned worktree
+with purpose recorded when needed; keep its cleanup obligation open. When
+cleanup is authorized and required delivery/retention evidence exists:
+
+1. archive required evidence;
+2. create CleanupRecord or project equivalent;
+3. remove only the owned merged worktree and branch;
+4. verify removal;
+5. release claim.