AppSDK Project Governance
Purpose and mandatory boundary
AppSDK verifies engineering quality. Collab supports automatic multi-worker
registration, communication and task/file ownership. Memory and Guidance help
when useful. Missing auxiliary state does not fail independent development.
Default flow: understand goal/scope → implement → relevant verification →
review → authorized delivery. Require applicable quality, safety and evidence
integrity gates; do not turn every available command into a mandatory phase.
Run project commands from project cwd. An explicit optional project path is for
operators intentionally working elsewhere; no project-root environment variable.
One global AppSDK binary
Do not copy or select AppSDK binaries by hand. The AppSDK repository's only
supported global installation entry is:
scripts/install-global-appsdk.sh
It builds the release, atomically replaces the executable beside the active
cargo, removes exact AppSDK-managed legacy copies, and checks that one
managed appsdk remains. Run it from any directory; it resolves its own
repository root. SHA-256 is diagnostic output only, not a fixed admission
condition. Do not stop project development because a historical binary hash
differs. If the version or command path is wrong, run the installer once and
refresh the current shell cache (rehash in zsh or hash -r in bash); do not
manually copy, rename, or leave .local/lib/appsdk/<version>/appsdk beside the
canonical entry.
An AppSDK binary install does not restart a daemon. Use the daemon's official
maintenance command separately when the running process must load the new
binary. Never start v2 or create a second global AppSDK entry as a workaround.
Reset legacy governance
When an old version has left incompatible records, stale audit reports, or
rebuildable delivery output, do not patch or hand-edit those files. In a clean
non-main owner worktree, after the user explicitly authorizes discarding the
named legacy control plane, run once:
appsdk reset-governance --discard-legacy
appsdk init
appsdk guide init --task governance-reset --mode bootstrap --module app-core
appsdk guide compile
appsdk verify
appsdk compile
reset-governance is idempotent. It removes the old .appsdk/ records and
maps (including old audit/migration reports), .appsdk-control/, and the
rebuildable generated/ projection, then creates a fresh current contract and
writes a reset record. It preserves business source, runtime data, active/,
and protected/ by default. Existing Active/Protected artifacts are not
silently deleted; if they are obsolete, request exact paths and perform a
separate authorized cleanup with its own evidence. Never run reset in main,
on a dirty worktree, against another worker's claim, or while inventing a
migration record. A reset is a new governance baseline, not proof that old
delivery or review was completed.
Legacy audit and delivery output handling
Before reset, classify every old item; do not treat a filename as proof of
current truth:
.appsdk/records/**, .appsdk/transactions/**, and AppSDK audit/migration
reports are legacy control-plane state. Preserve a small inventory or
immutable snapshot in the run note when audit history matters; then let
reset-governance --discard-legacy remove the old control plane. Do not
copy old PASS, hashes, receipts, or review results into the new baseline.
- The project-declared
governance.generated_root and module-declared
rebuildable outputs are disposable delivery projections. The reset command
removes the declared generated root (plus the standard generated/ root)
without deleting business source or published state.
- Failed transaction staging under
.appsdk/ is removed with the discarded
control plane. If it belongs to a still-valid current task, use that task's
canonical retry/abort operation before reset; never delete staging by hand.
- Reports or outputs outside those declared roots (
dist/, .deploy/,
build/, tmp/, custom report folders, or vendor output) are not assumed
disposable. Retain them or archive them until the project owner identifies
the exact path as rebuildable and authorizes its separate cleanup.
active/, protected/, runtime data, source, and human project documents
are retained by reset. Removing obsolete Active/Protected or historical
documents requires exact paths, explicit authorization, and a separate
cleanup record.
After reset, report removed and retained classes separately. A clean directory
is not evidence that delivery, review, install, restart, or freeze happened.
Working loop
- Read project AGENTS and affected code/contracts. Resolve owner, scope,
acceptance and relevant gates. Read historical notes only when they help.
- Use a clean owner worktree from latest origin/main. Preserve others' work.
For multi-worker work, automatically register the peer, communications and
task/file scope through official Collab; enforce overlap/resource ownership.
- Implement the smallest adequate change. Use existing design for local work;
clarify only material unknowns. Do not require a new plan or approval when
scope is already authorized and clear.
- Run applicable tests, necessary build and actual entrypoint checks. Install
and restart only when required by the delivery object. Fix failures at their
owner, never forge evidence or hide errors.
- Review exact validated changes under the shared review standard. Block
concrete correctness, safety, contract or material structural regressions;
optional simplifications are advisory.
- Reuse still-valid evidence when relevant source, inputs, dependencies,
configuration, artifact and environment remain unchanged. Rerun affected
checks after changes; verify an altered integration candidate.
- Deliver within authorization. Report test, review, merge, install, publish
and resource cleanup as separate achieved states.
Mainline delivery gate
Every AppSDK or runtime change uses this order:
clean playground worktree
-> candidate tests/build
-> independent review
-> clean main integration
-> main tests/build
-> push + remote receipt
-> official global install
-> exact service-scoped restart
-> deployed public-entrypoint replay
-> task/worktree cleanup and close
These are separate evidence states. A candidate, review PASS, local merge,
remote push, installed binary, daemon restart, live replay, or cleanup receipt
does not imply any other state. Never install or restart from a worker branch.
Required delivery procedure
Create playground/<slug> from current origin/main. The worker never
edits main or shares a worktree.
Run focused tests, relevant full suite, formatter, diff check, and release
build. Record the candidate commit, tree, artifact, and exact commands.
Use an independent review and replay the unchanged-source effectiveness
case. Review PASS is required before integration.
Integrate only into a clean local main. If tracked or untracked user
changes exist, stop and report exact paths; never reset, restore, stash,
overwrite, or silently absorb them.
Re-run affected tests, full tests, formatter, diff check, and release build
on the exact merged commit. Record the merge commit and artifact hash.
Push only that tested main commit. Verify remote truth with
git ls-remote <remote> <ref>; a local tracking ref is not publication.
Install through the canonical AppSDK entry point:
scripts/install-global-appsdk.sh
appsdk version
shasum -a 256 "$(command -v appsdk)"
Preserve source commit, installed path, version, and digest. Do not copy a
binary by hand or leave a second global SDK entry.
Restart only affected services with their official service-scoped command.
For Collab, use exactly:
env -u TMUX_PANE collab down
env -u TMUX_PANE collab up
Run this once per exact project root. Record old/new PID, socket, binary
path, and digest. Never use pkill, killall, xargs kill, or broad PID
commands.
Run the deployed public-entrypoint replay and negative path. For Collab,
verify collab who, collab context, collab task status, collab inbox,
one real notification/consume path, and single-daemon identity after
restart. Source tests are not live replay evidence.
Only after remote receipt, install/restart, and replay pass may the owner
release its claim and clean its own worktree through the official task
close operation. Cleanup records the removed path and receipt; it never
deletes another task's worktree, mailbox, journal, or token.
If a gate fails, preserve the exact error and leave the task explicitly
blocked with owner, unblock condition, next check, and recovery trigger. Never
report deployed from a candidate branch, merged from a local-only ref, or
complete from tests without mainline, install, restart, and replay evidence.
Optional Guidance
Use appsdk guide status/init/plan/update/next/close when the user/project
selects persistent planning or a long task benefits from recovery. Default
advisory and warning do not require a task plan or setup before development.
Missing PlanRecord does not fail ordinary verify or compile.
When using Guidance, follow its declared transitions and bind observations to
the current context. A failed optional workflow is not a failed quality gate.
Do not fabricate a successful step to close a plan.
For a requested setup/upgrade, guide init --mode bootstrap is read-only.
Compare current project-owned sources with the advisory standard template;
apply only authorized rule changes. appsdk init refreshes SDK resources but
never overwrites project AGENTS, Skills, records, Active or Protected. Merely
auditing rules does not require running initialization or changing setup.
Automatic Collab
Persistent subagents and project-specific notification policy:
subagents-config.md. All policies live in
~/.appsdk/config.toml; appsdk config shows effective configuration.
appsdk subagent start/list/status/send/close delegates to the Collab owner.
appsdk init attempts official collab init once in a live tmux peer, preserving
the inherited environment. Successful initialization registers identity and the
finite direct-message subscription. Do not duplicate that initialization.
Once task/worktree scope is known, use the Collab task lifecycle to register
feature/resource and file ownership before concurrent edits. Do not invent
task scope inside AppSDK initialization.
No tmux peer means pending. An unavailable/failed Collab reports its error;
independent work continues, while operations requiring shared ownership wait.
Keep automatic communication and file/task collaboration enabled; a serial
merge queue is required only when the project selects that integration mode.
Its ownership and tested-integration protections remain mandatory.
Universal Bug Tracking & Defect Governance
All user inputs—whether bug reports or new feature requests—are tracked through appsdk bug backed by git-bug.
1. Requirements Triage & Kanban Management
- Master Role:
- Worker / Subagent Role:
- Receives assigned issue and inspects its history:
appsdk bug show <id> --json.
- Verifies and reproduces the defect/feature in an isolated worktree.
- Reports discoveries or new bugs to the bug system immediately; does not auto-fix unrelated discoveries to stay focused on the primary objective.
- Blocker Handling & Block Criteria:
- Task status can be marked as
blocked (collab task block <id>) only with a concrete cause, responsible owner, unblock condition, and recovery trigger. Genuine external dependencies, resource ownership, missing credentials/approval, and cross-owner decisions may be valid waits; difficulty alone is not.
- AppSDK framework defects remain an upstream bug path (
appsdk bug new --upstream -t "[SDK Bug] ..." -l "P0,cli"), but non-framework failures must first be investigated and solved in scope. If a cross-owner decision is required, report a concrete proposal to Master; Master must take over, reassign, or auditable-force-close in the same cycle.
- If encountering a valid AppSDK blocker and a live Master exists: report immediately to Master with root cause and proposed fix (
collab sendmessage --to <master> --subject blocker "...").
- If blocked by AppSDK and no live Master exists: file an upstream SDK bug, resolve or work around, and resume the task.
2. Multi-Criteria Filtering
- Master and workers filter issues to reduce noise:
- By status:
appsdk bug list --status <open|closed>
- By label:
appsdk bug list -l <labels>
- By participant/author:
appsdk bug list -p <user> -a <author>
- By keyword query:
appsdk bug list -q <query>
- By sort & direction:
appsdk bug list -b <creation|edit> -d <asc|desc>
3. Lifecycle Evidence Enforcement
Long-Horizon Goal Subscription & Master Saturation
collab init / whoami returns role_brief; treat it as the active contract.
Master dispatches rather than codes: split and assign work, allocate resources,
keep workers loaded, own blockers, and drive verify/merge/cleanup/close.
Independent worker owns its task end to end and evaluates master collaboration
requests against current ownership/capacity—accept non-conflicting work or
negotiate explicitly. Managed subagent executes its assigned scope and reports
evidence to parent/master. On trouble, worker/subagent first investigates, then
reports root cause, attempts, proposed fix, and exact decision needed.
Notifications are interrupts, not completion. Follow the P0/P1/P2 ACTION,
then resume current work; with no task, run appsdk longhorizon show. Never end
on ACK, read, or summary.
Register complex or long-running goals with a required markdown target and periodic reminder interval:
appsdk goal subscribe --goal docs/goals/<feature>-plan.md --interval 10m
- Path must point to an existing markdown file (
.md).
- Master is awakened periodically to:
- Inspect worker states (
collab who / appsdk subagent status); dispatch decomposed tasks to keep workers saturated whenever any worker is idle.
- Enforce AppSDK lifecycle governance across all subagent tasks.
- Report any upstream AppSDK framework issues via
appsdk bug new --upstream.
- Conclude only when all goal DoD conditions pass.
Evidence and state ownership
- Project AGENTS owns project facts; Skills own procedure; declared machine
contracts own enforceable gates. Existing lifecycle records remain the sole
evidence truth. Plans, notes and Collab statuses do not duplicate PASS.
- Runtime review admission retains whitebox, public-entrypoint blackbox and
exact candidate/artifact/environment identity. Module
deployment_operations
declares required install/restart receipts; omission retains both for
compatibility, [] means neither operation applies. Bind this choice before
validation; changes invalidate artifact identity. Every supplied receipt is
checked. A missing required capability remains a blocker.
- Review confidence scores are optional annotation, never proof of quality.
- Freeze/Active/Protected apply when immutable artifact publication is in
scope. Do not require freezing for a documentation edit or ordinary review.
- Engineering delivery may complete with a retained worktree. Keep ownership
and cleanup obligations explicit; only claim resource closure after actual
safe cleanup. No forced deletion to make a task appear complete.
- Memory is optional. No automatic durable memory/rule promotion. Long tasks
and handoffs may record concise decisions and references to existing evidence.
Memory migration and re-entry are explicit independent operations: use
project-memory migrate for a source-preserving, resumable schema move and
project-memory index|export to render old and current raw records as a
Markdown index/details directory; after an intentional detail edit, use
project-memory import to append the change back to raw history. Markdown
is an interchange view, not a second truth store.
Normal memory writes use one project-memory entry invocation, which writes
the raw event and regenerates detail/index/projection together; do not hand
write one of those derived files as a separate step.
memory/index.md contains fixed-size Skill description candidates. Their L2/L3
lines already include the kind, tags, and relative L2/ or L3/ detail path.
During initialization or an intentional refresh, manually carry deduplicated
L1 lines into the project Skill description, then fill unused slots with L2
and L3 lines. Memory writes never rewrite Skill descriptions automatically.
project-memory reentry [project] --run <run-id> to resume the same run after
interruption. A missing or rebuilding memory index is not a governance
failure, and memory state must not be reconstructed from Guide, debug,
develop, or log payloads.
References: load only the relevant domain
- Initialization or migration: bootstrap-migration.md.
- Development/debug: development-debug.md.
- Runtime review/delivery/freeze: review-delivery.md.
- Selected persistent planning: process-control-harness.md.
- Contract errors/compatibility: contracts-and-failures.md.
- Explicit goal-prompt request: goal-prompt.md.
Failure reports name the failed applicable gate, preserved state, owner and next
action. Never infer deployed success, merge, freeze or cleanup from an earlier
test or an auxiliary workflow close.
1---2name: appsdk-project-governance-43description: "AppSDK engineering quality gates and Universal Bug Tracking (appsdk bug new/list/show/comment/close): all user inputs (features & defects) are tracked as bugs. Master triages via `appsdk bug list -q`, reopens or creates `appsdk bug new -t -m -l \"P0,mod\"`, manages Kanban priorities, and dispatches workers. Worker inspects `appsdk bug show`, stays focused, reports new discoveries via `appsdk bug new` without auto-fixing, reports blockers to master, and closes with `appsdk bug close ID -m \"Solution: ...\"`. Dependency managed via `appsdk setup-deps [--check]`. Use optional Guidance for planning; keep automatic Collab separate from quality admission."4---56# AppSDK Project Governance78## Purpose and mandatory boundary910AppSDK verifies engineering quality. Collab supports automatic multi-worker11registration, communication and task/file ownership. Memory and Guidance help12when useful. Missing auxiliary state does not fail independent development.1314Default flow: understand goal/scope → implement → relevant verification →15review → authorized delivery. Require applicable quality, safety and evidence16integrity gates; do not turn every available command into a mandatory phase.1718Run project commands from project cwd. An explicit optional project path is for19operators intentionally working elsewhere; no project-root environment variable.2021## One global AppSDK binary2223Do not copy or select AppSDK binaries by hand. The AppSDK repository's only24supported global installation entry is:2526```bash27scripts/install-global-appsdk.sh28```2930It builds the release, atomically replaces the executable beside the active31`cargo`, removes exact AppSDK-managed legacy copies, and checks that one32managed `appsdk` remains. Run it from any directory; it resolves its own33repository root. SHA-256 is diagnostic output only, not a fixed admission34condition. Do not stop project development because a historical binary hash35differs. If the version or command path is wrong, run the installer once and36refresh the current shell cache (`rehash` in zsh or `hash -r` in bash); do not37manually copy, rename, or leave `.local/lib/appsdk/<version>/appsdk` beside the38canonical entry.3940An AppSDK binary install does not restart a daemon. Use the daemon's official41maintenance command separately when the running process must load the new42binary. Never start v2 or create a second global AppSDK entry as a workaround.4344## Reset legacy governance4546When an old version has left incompatible records, stale audit reports, or47rebuildable delivery output, do not patch or hand-edit those files. In a clean48non-`main` owner worktree, after the user explicitly authorizes discarding the49named legacy control plane, run once:5051```bash52appsdk reset-governance --discard-legacy53appsdk init54appsdk guide init --task governance-reset --mode bootstrap --module app-core55appsdk guide compile56appsdk verify57appsdk compile58```5960`reset-governance` is idempotent. It removes the old `.appsdk/` records and61maps (including old audit/migration reports), `.appsdk-control/`, and the62rebuildable `generated/` projection, then creates a fresh current contract and63writes a reset record. It preserves business source, runtime data, `active/`,64and `protected/` by default. Existing Active/Protected artifacts are not65silently deleted; if they are obsolete, request exact paths and perform a66separate authorized cleanup with its own evidence. Never run reset in `main`,67on a dirty worktree, against another worker's claim, or while inventing a68migration record. A reset is a new governance baseline, not proof that old69delivery or review was completed.7071### Legacy audit and delivery output handling7273Before reset, classify every old item; do not treat a filename as proof of74current truth:7576- `.appsdk/records/**`, `.appsdk/transactions/**`, and AppSDK audit/migration77 reports are legacy control-plane state. Preserve a small inventory or78 immutable snapshot in the run note when audit history matters; then let79 `reset-governance --discard-legacy` remove the old control plane. Do not80 copy old PASS, hashes, receipts, or review results into the new baseline.81- The project-declared `governance.generated_root` and module-declared82 rebuildable outputs are disposable delivery projections. The reset command83 removes the declared generated root (plus the standard `generated/` root)84 without deleting business source or published state.85- Failed transaction staging under `.appsdk/` is removed with the discarded86 control plane. If it belongs to a still-valid current task, use that task's87 canonical retry/abort operation before reset; never delete staging by hand.88- Reports or outputs outside those declared roots (`dist/`, `.deploy/`,89 `build/`, `tmp/`, custom report folders, or vendor output) are not assumed90 disposable. Retain them or archive them until the project owner identifies91 the exact path as rebuildable and authorizes its separate cleanup.92- `active/`, `protected/`, runtime data, source, and human project documents93 are retained by reset. Removing obsolete Active/Protected or historical94 documents requires exact paths, explicit authorization, and a separate95 cleanup record.9697After reset, report removed and retained classes separately. A clean directory98is not evidence that delivery, review, install, restart, or freeze happened.99100## Working loop1011021. Read project AGENTS and affected code/contracts. Resolve owner, scope,103 acceptance and relevant gates. Read historical notes only when they help.1042. Use a clean owner worktree from latest origin/main. Preserve others' work.105 For multi-worker work, automatically register the peer, communications and106 task/file scope through official Collab; enforce overlap/resource ownership.1073. Implement the smallest adequate change. Use existing design for local work;108 clarify only material unknowns. Do not require a new plan or approval when109 scope is already authorized and clear.1104. Run applicable tests, necessary build and actual entrypoint checks. Install111 and restart only when required by the delivery object. Fix failures at their112 owner, never forge evidence or hide errors.1135. Review exact validated changes under the shared review standard. Block114 concrete correctness, safety, contract or material structural regressions;115 optional simplifications are advisory.1166. Reuse still-valid evidence when relevant source, inputs, dependencies,117 configuration, artifact and environment remain unchanged. Rerun affected118 checks after changes; verify an altered integration candidate.1197. Deliver within authorization. Report test, review, merge, install, publish120 and resource cleanup as separate achieved states.121122## Mainline delivery gate123124Every AppSDK or runtime change uses this order:125126```text127clean playground worktree128 -> candidate tests/build129 -> independent review130 -> clean main integration131 -> main tests/build132 -> push + remote receipt133 -> official global install134 -> exact service-scoped restart135 -> deployed public-entrypoint replay136 -> task/worktree cleanup and close137```138139These are separate evidence states. A candidate, review PASS, local merge,140remote push, installed binary, daemon restart, live replay, or cleanup receipt141does not imply any other state. Never install or restart from a worker branch.142143### Required delivery procedure1441451. Create `playground/<slug>` from current `origin/main`. The worker never146 edits `main` or shares a worktree.1472. Run focused tests, relevant full suite, formatter, diff check, and release148 build. Record the candidate commit, tree, artifact, and exact commands.1493. Use an independent review and replay the unchanged-source effectiveness150 case. Review PASS is required before integration.1514. Integrate only into a clean local `main`. If tracked or untracked user152 changes exist, stop and report exact paths; never reset, restore, stash,153 overwrite, or silently absorb them.1545. Re-run affected tests, full tests, formatter, diff check, and release build155 on the exact merged commit. Record the merge commit and artifact hash.1566. Push only that tested main commit. Verify remote truth with157 `git ls-remote <remote> <ref>`; a local tracking ref is not publication.1587. Install through the canonical AppSDK entry point:159160 ```bash161 scripts/install-global-appsdk.sh162 appsdk version163 shasum -a 256 "$(command -v appsdk)"164 ```165166 Preserve source commit, installed path, version, and digest. Do not copy a167 binary by hand or leave a second global SDK entry.1688. Restart only affected services with their official service-scoped command.169 For Collab, use exactly:170171 ```bash172 env -u TMUX_PANE collab down173 env -u TMUX_PANE collab up174 ```175176 Run this once per exact project root. Record old/new PID, socket, binary177 path, and digest. Never use `pkill`, `killall`, `xargs kill`, or broad PID178 commands.1799. Run the deployed public-entrypoint replay and negative path. For Collab,180 verify `collab who`, `collab context`, `collab task status`, `collab inbox`,181 one real notification/consume path, and single-daemon identity after182 restart. Source tests are not live replay evidence.18310. Only after remote receipt, install/restart, and replay pass may the owner184 release its claim and clean its own worktree through the official task185 close operation. Cleanup records the removed path and receipt; it never186 deletes another task's worktree, mailbox, journal, or token.187188If a gate fails, preserve the exact error and leave the task explicitly189blocked with owner, unblock condition, next check, and recovery trigger. Never190report deployed from a candidate branch, merged from a local-only ref, or191complete from tests without mainline, install, restart, and replay evidence.192193## Optional Guidance194195Use `appsdk guide status/init/plan/update/next/close` when the user/project196selects persistent planning or a long task benefits from recovery. Default197`advisory` and `warning` do not require a task plan or setup before development.198Missing PlanRecord does not fail ordinary `verify` or `compile`.199200When using Guidance, follow its declared transitions and bind observations to201the current context. A failed optional workflow is not a failed quality gate.202Do not fabricate a successful step to close a plan.203204For a requested setup/upgrade, `guide init --mode bootstrap` is read-only.205Compare current project-owned sources with the advisory standard template;206apply only authorized rule changes. `appsdk init` refreshes SDK resources but207never overwrites project AGENTS, Skills, records, Active or Protected. Merely208auditing rules does not require running initialization or changing setup.209210## Automatic Collab211212Persistent subagents and project-specific notification policy:213[subagents-config.md](references/subagents-config.md). All policies live in214`~/.appsdk/config.toml`; `appsdk config` shows effective configuration.215`appsdk subagent start/list/status/send/close` delegates to the Collab owner.216217`appsdk init` attempts official `collab init` once in a live tmux peer, preserving218the inherited environment. Successful initialization registers identity and the219finite direct-message subscription. Do not duplicate that initialization.220Once task/worktree scope is known, use the Collab task lifecycle to register221feature/resource and file ownership before concurrent edits. Do not invent222task scope inside AppSDK initialization.223224No tmux peer means pending. An unavailable/failed Collab reports its error;225independent work continues, while operations requiring shared ownership wait.226Keep automatic communication and file/task collaboration enabled; a serial227merge queue is required only when the project selects that integration mode.228Its ownership and tested-integration protections remain mandatory.229230## Universal Bug Tracking & Defect Governance231232All user inputs—whether bug reports or new feature requests—are tracked through `appsdk bug` backed by `git-bug`.233234### 1. Requirements Triage & Kanban Management235- **Master Role**:236 - Receives user inputs / feature requests / bug reports.237 - Queries existing issues first: `appsdk bug list -q "<keyword>" -l "<label>" --json`.238 - If an existing related issue is found, **reopen** it and append details.239 - If new, creates a new issue:240 ```bash241 appsdk bug new -t "<title>" -m "<requirements & reproduction>" -l "<priority>,<module>"242 ```243 - Prioritizes backlog using labels (e.g. `p0`, `p1`, `p2`) and dispatches workers based on highest priority issues within scope.244- **Worker / Subagent Role**:245 - Receives assigned issue and inspects its history: `appsdk bug show <id> --json`.246 - Verifies and reproduces the defect/feature in an isolated worktree.247 - Reports discoveries or new bugs to the bug system immediately; **does not auto-fix unrelated discoveries** to stay focused on the primary objective.248 - **Blocker Handling & Block Criteria**:249 - Task status can be marked as `blocked` (`collab task block <id>`) only with a concrete cause, responsible owner, unblock condition, and recovery trigger. Genuine external dependencies, resource ownership, missing credentials/approval, and cross-owner decisions may be valid waits; difficulty alone is not.250 - AppSDK framework defects remain an upstream bug path (`appsdk bug new --upstream -t "[SDK Bug] ..." -l "P0,cli"`), but non-framework failures must first be investigated and solved in scope. If a cross-owner decision is required, report a concrete proposal to Master; Master must take over, reassign, or auditable-force-close in the same cycle.251 - If encountering a valid AppSDK blocker and a live Master exists: report immediately to Master with root cause and proposed fix (`collab sendmessage --to <master> --subject blocker "..."`).252 - If blocked by AppSDK and no live Master exists: file an upstream SDK bug, resolve or work around, and resume the task.253254### 2. Multi-Criteria Filtering255- Master and workers filter issues to reduce noise:256 - By status: `appsdk bug list --status <open|closed>`257 - By label: `appsdk bug list -l <labels>`258 - By participant/author: `appsdk bug list -p <user> -a <author>`259 - By keyword query: `appsdk bug list -q <query>`260 - By sort & direction: `appsdk bug list -b <creation|edit> -d <asc|desc>`261262### 3. Lifecycle Evidence Enforcement263- **Architecture Gate**: `WorktreeRecord` must declare `bug_triage` (`query_executed: true`, a query containing the issue ID, `mode`, `reopened_from_issue_id`) verifying that existing issues were triaged before creating new work.264- **Promotion / Closure Gate**: Closing a bug or promoting a candidate requires solution documentation in `git-bug`:265 ```bash266 appsdk bug close <bug_id> -m "Solution: <root cause & resolution>" --receipt-id <receipt_id>267 ```268- **Legacy Compatibility**: Tasks with empty, `none`, or `legacy-*` `issue_id` are exempt from retroactive bug tracking enforcement.269270## Long-Horizon Goal Subscription & Master Saturation271272`collab init` / `whoami` returns `role_brief`; treat it as the active contract.273Master dispatches rather than codes: split and assign work, allocate resources,274keep workers loaded, own blockers, and drive verify/merge/cleanup/close.275Independent worker owns its task end to end and evaluates master collaboration276requests against current ownership/capacity—accept non-conflicting work or277negotiate explicitly. Managed subagent executes its assigned scope and reports278evidence to parent/master. On trouble, worker/subagent first investigates, then279reports root cause, attempts, proposed fix, and exact decision needed.280281Notifications are interrupts, not completion. Follow the `P0/P1/P2 ACTION`,282then resume current work; with no task, run `appsdk longhorizon show`. Never end283on ACK, read, or summary.284285Register complex or long-running goals with a required markdown target and periodic reminder interval:286287```bash288appsdk goal subscribe --goal docs/goals/<feature>-plan.md --interval 10m289```290- Path must point to an existing markdown file (`.md`).291- Master is awakened periodically to:292 1. Inspect worker states (`collab who` / `appsdk subagent status`); dispatch decomposed tasks to keep workers saturated whenever any worker is idle.293 2. Enforce AppSDK lifecycle governance across all subagent tasks.294 3. Report any upstream AppSDK framework issues via `appsdk bug new --upstream`.295 4. Conclude only when all goal DoD conditions pass.296297## Evidence and state ownership298299- Project AGENTS owns project facts; Skills own procedure; declared machine300 contracts own enforceable gates. Existing lifecycle records remain the sole301 evidence truth. Plans, notes and Collab statuses do not duplicate PASS.302- Runtime review admission retains whitebox, public-entrypoint blackbox and303 exact candidate/artifact/environment identity. Module `deployment_operations`304 declares required `install`/`restart` receipts; omission retains both for305 compatibility, `[]` means neither operation applies. Bind this choice before306 validation; changes invalidate artifact identity. Every supplied receipt is307 checked. A missing required capability remains a blocker.308- Review confidence scores are optional annotation, never proof of quality.309- Freeze/Active/Protected apply when immutable artifact publication is in310 scope. Do not require freezing for a documentation edit or ordinary review.311- Engineering delivery may complete with a retained worktree. Keep ownership312 and cleanup obligations explicit; only claim resource closure after actual313 safe cleanup. No forced deletion to make a task appear complete.314- Memory is optional. No automatic durable memory/rule promotion. Long tasks315 and handoffs may record concise decisions and references to existing evidence.316 Memory migration and re-entry are explicit independent operations: use317 `project-memory migrate` for a source-preserving, resumable schema move and318 `project-memory index|export` to render old and current raw records as a319 Markdown index/details directory; after an intentional detail edit, use320 `project-memory import` to append the change back to raw history. Markdown321 is an interchange view, not a second truth store.322 Normal memory writes use one `project-memory entry` invocation, which writes323 the raw event and regenerates detail/index/projection together; do not hand324 write one of those derived files as a separate step.325 `memory/index.md` contains fixed-size Skill description candidates. Their L2/L3326 lines already include the kind, tags, and relative `L2/` or `L3/` detail path.327 During initialization or an intentional refresh, manually carry deduplicated328 L1 lines into the project Skill description, then fill unused slots with L2329 and L3 lines. Memory writes never rewrite Skill descriptions automatically.330 `project-memory reentry [project] --run <run-id>` to resume the same run after331 interruption. A missing or rebuilding memory index is not a governance332 failure, and memory state must not be reconstructed from Guide, debug,333 develop, or log payloads.334335## References: load only the relevant domain336337- Initialization or migration: [bootstrap-migration.md](references/bootstrap-migration.md).338- Development/debug: [development-debug.md](references/development-debug.md).339- Runtime review/delivery/freeze: [review-delivery.md](references/review-delivery.md).340- Selected persistent planning: [process-control-harness.md](references/process-control-harness.md).341- Contract errors/compatibility: [contracts-and-failures.md](references/contracts-and-failures.md).342- Explicit goal-prompt request: [goal-prompt.md](references/goal-prompt.md).343344Failure reports name the failed applicable gate, preserved state, owner and next345action. Never infer deployed success, merge, freeze or cleanup from an earlier346test or an auxiliary workflow close.