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

package/skills/appsdk-project-governance/references/bootstrap-migration.md

@@ -0,0 +1,482 @@
+# Bootstrap and Migration
+
+## New project
+
+```text
+requirements + acceptance
+-> appsdk prepare
+-> confirm project root/boundaries/non-goals
+-> appsdk init
+-> optional approved Guidance setup/compile
+-> appsdk verify
+-> clean owner worktree
+```
+
+`init` is idempotent. It fills missing governance resources and preserves
+business files. AppSDK project initialization remains its own owner and may
+invoke the daemon context internally when a live Codex App Server sessionID
+binding exists. The agent must not rerun AppSDK initialization or run another
+identity command to repair pending Collab. For agent-facing Collab bootstrap,
+run `collab context` once. `registered: true` ends bootstrap. If the snapshot
+returns `required_fields`, supply only those real 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, recovery, registration, route publication, and lease
+restoration. If AppSDK reports Collab pending or context explicitly reports
+daemon DOWN or a runtime error, preserve the exact result and stop; daemon
+maintenance is human-authorized. Use `new` only for an empty destination.
+
+`appsdk prepare` is a hard gate. First invocation writes `.appsdk-prepare.json`
+with `status: "draft"`. `appsdk init` rejects an unconfirmed preparation with
+`PREPARATION_NOT_CONFIRMED`; it does not guess scope or boundaries. Rerunning
+`appsdk prepare` prints the existing record and does not overwrite it.
+
+Before `appsdk init`, the operator must explicitly confirm these fields in
+`.appsdk-prepare.json`:
+
+```json
+{
+  "schema_version": 1,
+  "preparation_id": "prepare-<slug>",
+  "status": "confirmed",
+  "objective": "One-sentence confirmed goal for AppSDK governance admission.",
+  "change_kind": "new_project",
+  "project_root": ".",
+  "legacy_roots": [],
+  "new_roots": [".appsdk/**", ".appsdk-control/**", "playground/**"],
+  "protected_roots": ["protected/**", ".git/**"],
+  "runtime_forbidden_roots": ["generated/**", ".agent-collab/**"],
+  "boundary": {
+    "allowed_paths": [".appsdk/**", "playground/**", "active/lib/**", "protected/**"],
+    "forbidden_paths": [".git/**", ".agent-collab/**", "dist/**"],
+    "payload_control_separation": "confirmed"
+  },
+  "acceptance_criteria": ["appsdk init completes", "appsdk verify passes"],
+  "non_goals": [],
+  "questions": [],
+  "confirmed_by": "Jason (explicit user approval)",
+  "confirmed_at": "2026-09-15T00:00:00Z"
+}
+```
+
+`change_kind` must be one of `new_project`, `module_refactor`,
+`project_refactor`, or `debug`. `project_root` is the relative AppSDK project
+root from the preparation file location; `.` means the same directory. All open
+questions must be answered or removed before `init`. Never confirm the record
+on behalf of the user, and never replace the preparation gate by editing
+`.appsdk/project.json` before initialization.
+
+For an existing project with prior `.appsdk/` or `.agent-collab/`, do not use
+this ordinary new-project path. Use
+[Existing project: remove old governance](#existing-project-remove-old-governance)
+and keep AppSDK and Collab reset/migration in separate transactions.
+
+AppSDK preserves the launching environment and does not pass a project path to
+Collab. The daemon resolves project scope from the exact process cwd. Without a
+live registered App Server transport, AppSDK initializes governance and
+reports Collab pending because no peer can be registered; it never fabricates
+subscription state.
+
+Collab bootstrap errors from AppSDK's internal context invocation are explicit
+warnings for AppSDK initialization. Automatic multi-worker registration and
+task/file coordination remain enabled; shared operations wait for reliable
+ownership while independent work continues.
+
+### Master and ordinary peer bootstrap
+
+For a project that will run multiple agents, initialize the AppSDK governance
+root first, then run one `collab context`. Through that invocation the daemon
+registers/establishes the current peer and its lease; role assignment is
+human-approved and separate.
+
+Master initialization, after user approval for the exact project and peer:
+
+```bash
+cd /abs/path/project
+appsdk prepare
+# confirm .appsdk-prepare.json exactly as above
+appsdk init .
+appsdk guide status
+appsdk verify
+collab context
+# 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
+```
+
+Do not promote while a live master already exists. `appsdk init` alone never
+creates master authority. If `appsdk init` reports Collab pending or a failed
+registration, preserve the exact error; do not report Collab as available and
+do not start a second daemon.
+
+Ordinary peer initialization, after the project already has
+`.appsdk/project.json` and a live master or parent:
+
+```bash
+cd /abs/path/project
+collab context
+# if required_fields are present, provide only those facts once
+```
+
+The peer must observe its own identity, liveness, presence, transport and peer
+role. Do not run a second identity bootstrap, do not promote itself, do
+not register a long-horizon goal, and do not fabricate a worker role from
+AppSDK initialization output.
+
+Long-horizon master scheduling is a separate, master-only step. Create the
+plan file first, then register and verify:
+
+```bash
+appsdk goal subscribe --goal docs/goals/<goal>-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 a null `error`. A successful command output is not
+proof that a timer fired. Run one short-interval live replay and record the
+armed subscription, fired deadline notification, and consumed result before
+declaring long-horizon scheduling verified. The current implementation is a
+one-shot deadline that must be explicitly rearmed with `appsdk goal subscribe`
+after it is consumed, expires, or Collab restarts.
+
+For a new governance root, AppSDK installs a project-neutral root `AGENTS.md`
+when none exists. It contains the Project Truth, Semantic Invariants,
+Ownership, Architecture Truth, Development Process Control, Git Protection,
+Task Routing, and Evidence Boundary sections used by Guide setup. Customize
+the bracketed project facts through the approved setup flow. Existing project
+rules are never overwritten, and rerunning `init` on an already governed root
+does not recreate a deliberately absent `AGENTS.md`.
+
+## Repeat initialization and template upgrade
+
+Initialization is not one-shot. After AppSDK is updated, or when the project
+wants to revisit its process, rerun `appsdk init` to refresh AppSDK-owned Bundle
+resources. It installs the current versioned standard reference at
+`.appsdk/templates/minimal/AGENTS.md` while preserving the project-owned
+`AGENTS.md`, local Skills, machine Guidance, lifecycle records, Active, and
+Protected state.
+
+```text
+appsdk init
+-> Agent reads effective upstream rules, project AGENTS/Skills, test commands,
+   and CI/hook entrypoints
+-> when Guidance is selected:
+   appsdk guide init --task guidance-upgrade --mode bootstrap --module <id>
+   compare retained rules and useful differences
+   GuidanceSetupProposal
+   reuse existing session authorization; approve only uncovered differences
+-> otherwise: perform the same audit directly
+-> latest origin/main clean owner worktree
+-> apply authorized changes
+-> when Guidance is selected: appsdk guide compile
+-> appsdk verify
+```
+
+The template is a standard reference, not an active rule source. Do not add it
+to `.appsdk/project.json#/guidance/rule_sources`, automatically overwrite
+project rules, or reset valid governance merely to adopt a newer template.
+The proposal records retained project rules, recommended changes, and declined
+template items so choosing not to adopt an item is explicit and valid.
+Guidance is optional for this audit. Repeated initialization and unrelated
+version refreshes do not trigger a whole-project rule audit.
+Missing or locally removed reference material does not fail ordinary
+`appsdk verify`; rerun `appsdk init` only when a fresh comparison is wanted.
+
+## Governance exists but Guide is missing
+
+Do not reset or migrate valid lifecycle truth merely to add Guide. Run
+idempotent initialization so the current AppSDK can install missing Guide
+resources while preserving the existing project contract, maps, records,
+Active, and Protected state.
+
+An already governed root containing `.appsdk/project.json` may rerun
+`appsdk init` directly; its existing project root is the authority, so a new
+preparation record is not required for this non-destructive resource refresh.
+Fresh or relocated initialization still requires confirmed preparation.
+
+```text
+appsdk init
+-> appsdk guide status
+-> GUIDANCE_SETUP_REQUIRED
+-> appsdk guide init --task guidance-setup --mode bootstrap
+-> Agent reads returned AGENTS and local Skill candidates
+-> Agent asks only unresolved questions
+-> Agent presents GuidanceSetupProposal
+-> reuse session authorization; approve only uncovered differences
+-> clean owner worktree updates AGENTS/local Skill/machine contract/source declaration
+-> appsdk guide compile
+-> appsdk verify
+```
+
+Bootstrap intake is read-only and may be invoked again after Guidance has been
+compiled. Candidate files are not compiled rule sources
+until the user approves them and `.appsdk/project.json` declares them. A
+task-level PlanProposal is not a substitute for this project-level setup and is
+never copied into a Skill automatically.
+
+## Existing project
+
+Inventory AppSDK roots, maps, records, Active/Protected, local control state,
+claims, and worktrees. Choose one route:
+
+### Preserve and migrate
+
+Use when historical evidence remains valuable and the current version has a
+supported canonical migration.
+
+```text
+snapshot immutable truth
+-> reconcile ownership/conflicts
+-> run canonical migration once
+-> verify one retained truth
+-> compile Harness rules
+```
+
+### Reset and reinitialize
+
+Use when old governance is obsolete, unsupported, or costs more than its audit
+value. Reset is destructive and requires user authorization for the named
+objects.
+
+```text
+inventory + immutable audit snapshot
+-> classify retained business source and Protected artifacts
+-> request exact reset/delete authority
+-> clean non-main owner worktree
+-> appsdk init <project> --fresh --discard-legacy
+-> old .appsdk audit/migration records and generated projection removed
+-> current .appsdk contract, record contracts, and transition manifest rebuilt
+-> rebuild maps/goal/module/owner from current project truth
+-> appsdk guide compile
+-> appsdk guide init for the current task/domain
+-> appsdk verify
+```
+
+`--fresh --discard-legacy` is an explicit existing-project initialization route,
+not ordinary `init` behavior. It requires `.appsdk/project.json`, a clean
+non-`main`/`master` worktree, and the discard confirmation. It preserves
+business source, runtime data, `active/`, `protected/`, and human documents;
+only the named AppSDK control plane and declared generated roots are removed.
+The current SDK scaffold is the only reset baseline: legacy SDK pins, migration
+witnesses, indexes, and SDK-owned contract projections are ignored and
+regenerated; missing SDK-owned fields are refilled. Project identity, module
+ownership, build, and protection boundaries are carried forward.
+The new reset record has `mode: "fresh_init"` and proves the reset operation
+only. It does not inherit old PASS, review, delivery, or freeze claims.
+
+Before choosing this route, install the reviewed current AppSDK and Collab
+versions globally and use only those installed binaries and Skills for the
+inventory. Do not read, replay, or interpret old local control history to make
+the old baseline compatible. The current version is the only reset baseline:
+missing SDK-owned fields are refilled, legacy SDK pins/migration witnesses are
+ignored, and old local control state is removed only through the canonical
+owner.
+
+The replacement order is:
+
+1. Install the reviewed AppSDK and Collab binaries/Skills.
+2. Inspect with the newly installed commands and record the exact old control
+   roots and owner.
+3. Retire or migrate Collab through the Collab owner.
+4. Reset AppSDK through the AppSDK owner in a clean non-main worktree.
+5. Validate the new baseline only. Do not import old PASS, receipts, review,
+   install, restart, or delivery evidence.
+
+If a legacy user-local Collab binary pair is proven by its own version
+response, removal requires explicit user authorization naming the exact binary
+paths. After the canonical pair is installed, remove only those authorized,
+verified paths. Never remove `~/.appsdk`, `~/.collab`, project
+`.agent-collab/`, or business source as part of binary cleanup.
+
+The lower-level `appsdk reset-governance <project> --discard-legacy` command remains
+available and uses the same transactional reset owner. Neither command
+authorizes manual deletion or hand-editing of version/hash/ReviewRecord, and
+neither permits two active governance roots. If old Active/Protected artifacts
+are also obsolete, name exact paths and authorize a separate cleanup.
+
+### What to do with old reports and delivery output
+
+Use ownership and rebuildability, not age, to decide what is removable:
+
+| Class | Default action | Reason |
+| --- | --- | --- |
+| `.appsdk/records`, `.appsdk/transactions`, audit/migration reports | Inventory/snapshot if needed, then remove through reset | Old control truth must not leak into the new baseline. |
+| Declared `governance.generated_root`, module generated outputs | Remove through reset and regenerate | These are reproducible projections, not source or release truth. |
+| Failed transaction staging | Canonical abort/retry if current; otherwise reset | Manual deletion can hide ownership or partial publication. |
+| `active/`, `protected/`, runtime data, business source | Retain | They may be the only published or operational truth. |
+| `dist/`, `.deploy/`, `build/`, `tmp/`, custom reports/artifacts | Keep until exact disposable ownership is confirmed | AppSDK cannot infer that an external output is safe to delete. |
+
+The reset command reads and validates the old project contract before removal,
+carries that contract into the new `.appsdk` root, and includes its declared
+generated root in the disposable set. It does not use a fixed project path or
+silently delete Active/Protected. For external outputs, the
+owner must name the exact path, establish that it is rebuildable, authorize
+cleanup, and record the result separately. Never preserve an old report by
+renaming it as a new record, and never make a new record by editing an old
+hash or receipt.
+
+## Mid-development adoption
+
+Do not force release/freeze evidence onto unfinished work.
+
+```text
+snapshot current source and task state
+-> initialize advisory governance
+-> bind current goal/module/owner/worktree
+-> if Guide is missing, complete the user-approved setup proposal first
+-> run task guide init, read declared AGENTS/Skills, ask unresolved questions
+-> place workflow at the current real phase
+-> apply new rules to new/changed nodes
+-> continue development
+```
+
+Untouched legacy gaps are warnings unless safety, source ownership, evidence
+truth, or current delivery is affected.
+
+## Existing project: remove old governance
+
+Use this section when a real project root already contains `.appsdk/`,
+`.appsdk-control/`, or `.agent-collab/` from an older version and the operator
+wants to start the current governance and coordination baseline instead of
+migrating old control state. The two roots have different owners and must be
+handled in separate transactions.
+
+### 1. Inventory and freeze
+
+Run read-only inventory from the project root. Do not delete anything yet.
+
+```bash
+cd /abs/path/project
+git status --short --branch
+git worktree list
+find .appsdk .appsdk-control .agent-collab -maxdepth 3 -print 2>/dev/null
+collab migrate inspect
+collab context
+```
+
+Record the exact project root, branch/HEAD, worktrees, `.appsdk/` and
+`.appsdk-control/` contents, generated roots, `active/`, `protected/`,
+`.agent-collab/` journal/mailbox/tasks/claims, daemon PID/socket, peer
+identities, routes, and migration blockers in the run note. A file name, old
+PID file, socket existence, or successful `collab status` is not sufficient
+proof of ownership.
+
+Stop new shared writes, dispatches, and task admission before either reset.
+Preserve every active worktree and task until its owner or an explicitly
+authorized migration decision resolves it.
+
+### 2. Collab migration or retirement
+
+`.agent-collab/` is owned by Collab. AppSDK reset does not remove it. If the
+project uses Collab v1 and the journal is replayable, use the authenticated
+migration transaction:
+
+```bash
+collab migrate inspect
+collab migrate plan
+collab migrate apply
+# install the reviewed Collab binary, then:
+collab down
+collab up
+collab context
+collab migrate verify
+```
+
+`inspect` is read-only. `plan` does not freeze admission. `apply` freezes
+admission and persists the deterministic snapshot. `verify` resumes admission
+only after journal/mailbox/task/identity continuity passes. If the result is
+`reset_required`, `needs_operator`, `unknown`, or an owner/count mismatch, stop
+and resolve it through Collab's canonical owner; do not continue to the AppSDK
+reset as if the whole operation passed.
+
+When the operator explicitly authorizes abandoning the old Collab epoch
+instead of preserving it, use the single offline reset owner:
+
+```bash
+collab down
+collab reset --project --discard-legacy --approval "<explicit user authorization>"
+collab up
+collab context
+```
+
+`collab reset` archives the exact `.agent-collab/` and `.agent-collab-v2/`
+bytes, removes only Collab-owned project control state and stale routes, and
+rebuilds the current empty baseline. It never removes `.appsdk/` or
+`.appsdk-control/` and records `delivery_verified: false`. Never manually
+delete `.agent-collab/`, edit its JSON/JSONL, clear its mailbox, copy identity
+tokens, or start a second daemon. A project that has no valid Collab state to
+preserve still needs this explicit Collab retirement or the migration
+decision; AppSDK must not make that decision for it.
+
+### 3. AppSDK reset
+
+After the Collab side is either migrated/verified or explicitly retired by its
+owner, handle `.appsdk/` from a clean non-`main` owner worktree with no
+competing claim. For a project that must abandon the old governance epoch and
+start from the current SDK baseline, the preferred single entry is:
+
+```bash
+cd /abs/path/project
+git worktree add -b codex/governance-reset-<slug> \
+  /Volumes/Intel/playground/<project-key>/<task-slug> origin/main
+cd /Volumes/Intel/playground/<project-key>/<task-slug>
+appsdk init "$PWD" --fresh --discard-legacy
+appsdk guide init --task governance-reset --mode bootstrap --module <module-id>
+appsdk guide compile
+appsdk verify
+appsdk compile
+```
+
+`<project-key>` and `<task-slug>` come from the current project and task. Do not
+reuse another task's worktree path.
+
+`appsdk init --fresh --discard-legacy` requires an existing
+`.appsdk/project.json`, a clean non-`main`/`master` worktree, and the explicit
+discard confirmation. It uses the same transactional reset owner as
+`appsdk reset-governance <project> --discard-legacy`, but combines reset with current
+contract rebuild. It removes the old AppSDK control plane, `.appsdk-control/`,
+and declared rebuildable generated roots; it preserves business source,
+runtime data, `active/`, and `protected/` by default. It must not remove
+`.agent-collab/`.
+
+If the operator explicitly chooses the lower-level AppSDK operation instead,
+run it in the same clean non-`main` worktree and then initialize:
+
+```bash
+appsdk reset-governance "$PWD" --discard-legacy
+appsdk init "$PWD"
+appsdk guide compile
+appsdk verify
+```
+
+Do not hand-edit `.appsdk/` JSON, reuse old PASS/hash/receipts, or delete
+`active/` or `protected/` as part of reset. Those are separate authorized
+cleanup decisions.
+
+If the old `.appsdk/project.json` is missing, malformed, unreadable, or the
+worktree is dirty, `--fresh --discard-legacy` must fail closed. Do not replace
+that check with manual deletion. Preserve the exact error and use the AppSDK
+migration owner to establish whether the project contract can be recovered;
+only an existing, valid contract can authorize a fresh reset. If no contract
+can be established, a new root must go through a separate confirmed
+preparation/init flow rather than claiming to reset the old project.
+
+### 4. Verify the new baseline
+
+The operation is complete only when all of the following are true:
+
+- Collab reports the exact migration/retirement result and has one verified
+  daemon/socket/identity state.
+- `appsdk verify` passes against the current project contract and the fresh
+  reset baseline.
+- The removed classes are limited to the authorized AppSDK control plane,
+  `.appsdk-control/`, and declared rebuildable generated roots.
+- Business source, runtime data, `active/`, `protected/`, and all retained
+  Collab evidence still exist.
+- The new reset record is current and does not claim delivery, review,
+  install, restart, or communication success.

package/skills/appsdk-project-governance/references/command-surface.md

@@ -0,0 +1,111 @@
+# AppSDK and Collab Command Surface
+
+Use these commands instead of guessing paths or running broad help exploration.
+This list is the decision path for normal setup, quality, delivery, and Collab
+work.
+
+## AppSDK commands
+
+```text
+appsdk prepare                         create or print .appsdk-prepare.json
+appsdk init .                          scaffold/refresh governance and register project
+appsdk init . --fresh --discard-legacy reset old AppSDK control plane and rebuild
+appsdk reset-governance . --discard-legacy
+                                       lower-level AppSDK control-plane reset
+appsdk new <dir>                       create an empty new governed project
+appsdk verify .                        verify current governance contract/baseline
+appsdk compile .                       compile project modules
+appsdk compile-module . --module <id>  compile one module
+appsdk pin-lock . --binary <path>      pin project to a binary and write sdk.lock
+appsdk guide status                    read compiled guidance status
+appsdk guide compile                   compile declared guidance after contract binding
+appsdk guide init --task <id> --mode <mode> --module <module-id>
+                                       create a task-specific guide plan
+appsdk goal subscribe --goal <file.md> --interval <interval>
+                                       master-only long-horizon registration
+appsdk goal status --json              verify goal subscription state
+appsdk longhorizon show --json         read long-horizon role/task state
+appsdk bug intake --input <json>       deduplicate/classify execution work and return issue_id
+appsdk bug list -q <kw> --json         query bug backlog
+appsdk bug new -t <title> -m <body> -l <labels>
+                                       create a bug record
+appsdk bug list ... --upstream         inspect upstream AppSDK defects
+appsdk bug new --upstream ...          report an AppSDK defect upstream
+appsdk bug show ... --upstream         read an upstream AppSDK defect
+appsdk bug show <id> --json            read a bug record
+appsdk bug close <id> -m <solution> --receipt-id <receipt>
+                                       close a bug with solution evidence
+appsdk subagent start --id <id>        start a managed subagent
+appsdk subagent status                 inspect managed subagents
+appsdk subagent send <id> --subject <topic> "<assignment>"
+                                       dispatch a managed subagent task
+appsdk subagent close <id>             close a managed subagent
+appsdk subworker <action>              compatibility entry for Collab subagent flow
+appsdk communication reset-runtime-registry --discard-legacy --approval "<text>"
+                                       archive legacy ~/.appsdk/runtimes.jsonl and rebuild current baseline
+project-memory entry                   append memory entry and regenerate projections
+project-memory reentry [project] --run <run-id>
+                                       resume a memory run after interruption
+```
+
+## Collab commands
+
+```text
+collab context                         single agent identity bootstrap and authority query
+collab context --provide '<JSON>'      supply only required missing facts once
+                                       (session_id/thread_id/endpoint/namespace only)
+collab sendmessage --to <peer> --subject <topic> "<body>"
+                                       send one durable ordinary message
+collab recv                            consume delivered notifications
+collab inbox                           list unread messages (read-only)
+collab msg <id>                        read one message without consuming
+collab ack <id> | --all                compatibility ACK for delivered messages
+collab master promote --approval "<text>"
+                                       promote this peer when user approves and no master exists
+collab master delegate <peer>          transfer live master authority
+collab master send --project <target> --to <target-master> --subject <topic> "<body>"
+                                       cross-project master-to-master send
+collab subagent dispatch --request-id <id> --subject <topic> "<assignment>"
+                                       scheduler-reserved dispatch
+collab task accept <task-id>           accept assigned task (assigned -> working)
+collab task update --status <state>    update task state
+collab task block <id>                 block with concrete cause/owner/unblock condition
+collab task close <id> [--force --reason "<reason>"]
+                                       close owned task
+collab migrate inspect                 read-only migration/retirement inspection
+collab migrate plan                    prepare migration/retirement snapshot
+collab migrate apply                   freeze admission and persist snapshot
+collab migrate verify                  verify migration/retirement continuity
+collab reset --project --discard-legacy --approval "<text>"
+                                       retire/rebuild Collab-owned local control plane
+collab down                            controlled daemon stop
+collab up                              controlled daemon start
+```
+
+The commands below are read-only operator diagnostics. They are not
+initialization, route recovery, or agent bootstrap steps. Do not chain them
+after `collab context` during setup. If context explicitly reports daemon DOWN
+or a runtime error, preserve the exact failure and stop; daemon lifecycle
+maintenance is human-authorized. See
+[`init-prompts.md`](init-prompts.md#stale-daemon-socket-or-lock).
+
+```text
+collab status --all                    server summary and worker/task state
+collab who                             registered peers and liveness
+collab worker status <peer-id>         one peer's identity/liveness/transport
+collab notify status                   own subscriptions
+```
+
+## Do not guess
+
+- Do not edit `~/.appsdk`, `~/.collab`, `.appsdk/`, `.appsdk-control/`, or
+  `.agent-collab/` by hand.
+- Do not delete project directories to clean global truth.
+- Do not use `--help` exploration as the setup path; read the referenced
+  lifecycle docs when a command's exact flag matters.
+- If a command returns an error, preserve the exact error and report it.
+  Never claim a route, migration, merge, install, restart, or delivery from
+  command output alone.
+- Do not run AppSDK or Collab initialization or operator diagnostics to repair
+  pending identity.
+  `collab context` and its one factual supplement are the only agent bootstrap.

package/skills/appsdk-project-governance/references/contracts-and-failures.md

@@ -0,0 +1,74 @@
+# Contracts and Failures
+
+## Severity
+
+- `advisory`: recommendation; never blocks.
+- `warning`: visible debt; current work may continue.
+- `forbidden`: unsafe or false transition; command stops.
+
+Forbidden defaults:
+
+- fabricated/empty evidence for required PASS;
+- non-adjacent transition within a selected workflow;
+- plan/event history overwrite or deletion;
+- stale project, goal, source, tree, scope, owner, Skill, AGENTS, or manifest;
+- committed governance mutation from main;
+- false review, delivery, promotion, freeze, or cleanup completion.
+
+Legacy optional metadata, historical strictness outside changed scope, missing
+release evidence during ordinary development, and absent parallel-worker data
+in a single-worker task are warnings or advisory.
+
+Architecture conformance is change-scoped. New or modified behavior that puts
+control truth in payload/metadata/log context, duplicates an owner or
+implementation in a way that breaks its contract, or mocks a required capability
+is forbidden. A project-declared operation/hook/gate boundary remains binding.
+Optional simplifications are advisory; direct code is not a violation merely
+because it could use configuration. The same pattern in untouched historical code
+is advisory unless it affects safety, ownership, evidence truth, or the current
+delivery boundary.
+
+## Compatibility
+
+Project-scoped commands resolve the project from the process `cwd` when their
+optional project argument is omitted. Do not require a project-root environment
+variable. `--help` is project-independent and must never resolve or validate a
+project.
+
+Harness does not check binary SHA. Existing AppSDK version/contract compatibility
+belongs to canonical lifecycle commands. A mismatch must return either a
+supported migration route or an authorized reset/reinitialize route; it must
+not trap development behind repeated byte-identity checks.
+
+`GUIDANCE_SETUP_REQUIRED` is not a lifecycle failure. It means existing
+governance has no approved Guide declaration. Only when Guidance is selected,
+run the returned read-only bootstrap intake, present `GuidanceSetupProposal`,
+reuse session authorization that covers a difference, and obtain explicit
+approval only for uncovered changes. Then update and compile project-owned rule
+sources. Do not report an external AppSDK blocker or retry compile against an
+undeclared rule set.
+
+## Failure output
+
+Required fields:
+
+```text
+first failing gate/code
+project/module/lifecycle projection
+preserved state
+retry_allowed
+canonical owner
+one executable next action
+```
+
+Do not retry unchanged failures. Do not hand-write records or hashes. Fix the
+first divergent owner, revise the plan if bound context changed, then execute
+once.
+
+## Worktree audit
+
+Every claim binds one branch and owner worktree. Resource close requires remote
+receipt when delivery is in scope, retention/cleanup record, worktree removal,
+removal verification, then claim release. Engineering delivery may be complete
+while an owned worktree is retained and its cleanup obligation stays open. An abandoned or foreign dirty
+worktree is preserved until its owner or explicit cleanup authorization exists.