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

package/skills/appsdk-project-governance/references/state-paths.md

@@ -0,0 +1,157 @@
+# AppSDK State Paths and Components
+
+## Global truth
+
+Host-wide AppSDK governance and Collab truth are separate:
+
+```text
+~/.appsdk
+  projects.jsonl
+  runtimes.jsonl
+  communication.jsonl
+  config.toml
+
+~/.collab
+  server.sock
+  daemon.lock
+  server.pid
+  events.jsonl
+  log.txt
+  routes.jsonl
+```
+
+Usage:
+
+- `~/.appsdk` is AppSDK's global persistent truth. It is not a project
+  directory. Do not hand-edit or delete its `.jsonl` files; AppSDK updates them
+  through its commands and reset/migration lifecycle.
+- `~/.collab` is Collab's host-level daemon truth. It is owned by Collab, not
+  AppSDK. Do not hand-edit or delete its files; see the Collab skill's
+  `state-paths.md`.
+- Deleting a project root does not authorize deleting global truth entries.
+  Global entries are retired through the owning lifecycle.
+
+## Project-local AppSDK state
+
+For a governed project root:
+
+```text
+<project>/.appsdk/
+  project.json
+  goal.json
+  sdk.lock
+  contracts/
+  records/
+  maps/
+  guidance/
+  skills/
+
+<project>/.appsdk-control/
+  run state
+  temporary guidance/harness output
+  local runtime state
+
+<project>/.agent-collab/
+  project registration/reducer input
+```
+
+Usage:
+
+- `.appsdk/project.json` is the project governance contract. After
+  `appsdk init`, it contains placeholder `project_id: "change-me"`, `goal.json`
+  contains `goal-change-me`, and the module scaffold contains `app-core`.
+  Replace those with the real project contract before `appsdk verify`.
+- `.appsdk-control/` is local runtime state and is not committed truth. It is
+  removed or reset through AppSDK reset/init, not by hand-deleting arbitrary
+  files.
+- `.agent-collab/` is Collab-owned project registration/reducer input. It is
+  not the peer, route, mailbox, task, or liveness truth. AppSDK reset must not
+  delete it; Collab migration/retirement owns it.
+- A Git worktree contains tracked `.appsdk/` files from its main checkout, but
+  does not inherit ignored `.agent-collab/` or `.appsdk-control/` state. The
+  registered peer identity is inherited from the global Collab state by the
+  current Codex sessionID/App Server thread; do not create a second project
+  registration from a worktree.
+
+## Lifecycle commands and meaning
+
+```text
+appsdk prepare                 -> create/confirm scope and boundaries
+appsdk init .                  -> scaffold/refresh governance and register project
+appsdk guide compile           -> compile declared guidance after binding the contract
+appsdk verify                  -> verify the current contract/baseline
+appsdk reset-governance <project> --discard-legacy
+                               -> AppSDK control-plane reset
+appsdk init --fresh --discard-legacy
+                               -> preferred single transaction for old AppSDK control plane
+collab down
+collab reset --project --discard-legacy --approval "<user text>"
+collab up
+collab context
+                               -> Collab-owned project control-plane reset
+```
+
+For old `.appsdk/` state, do not delete it manually. Use the authorized reset
+route after the Collab side is migrated or retired. `appsdk init --fresh
+--discard-legacy` removes the AppSDK-owned old control plane and rebuilds the
+current baseline; it does not delete `.agent-collab/` or global truth.
+
+When the user explicitly asks to start fresh instead of migrating legacy
+state, keep the owners separate:
+
+1. Use `collab migrate` when the project journal is replayable; otherwise use
+   the explicitly authorized `collab reset --project --discard-legacy` sequence above
+   for Collab-owned state. Do not manually remove `.agent-collab/`.
+2. From a clean non-`main` owner worktree, use `appsdk init --fresh
+   --discard-legacy` for `.appsdk/` and `.appsdk-control/`. Do not manually
+   remove either AppSDK-owned root.
+3. Initialize and bind the current project contract, then run `appsdk guide
+   compile` and `appsdk verify`. A reset proves only reset; it does not prove
+   delivery, review, install, restart, or communication.
+
+## Registration verification
+
+### Where registration and identity queries run
+
+`collab context` is the single agent identity bootstrap. AppSDK project
+initialization remains its own owner and may invoke the same daemon context
+internally; the agent must not rerun AppSDK initialization or run another
+identity command to repair pending Collab. Run `collab context` once from the
+project or worktree. Global Collab state resolves the current Codex
+sessionID/App Server thread to the canonical route and reports the inherited
+identity, liveness, tasks, inbox, `next_actions`, and master/authority state.
+`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.
+`collab context` is the registration truth for `authority`, `identity`, `inbox`, `liveness`,
+`master`, `next_actions`, `role_brief`, `tasks`, and
+`truth`. Registration returns the brief effective at registration; `collab
+context` projects the current brief, and promotion or delegation returns the
+replacement brief. Read master/authority state from the same 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. Do not run a separate master, route, or worker query for
+bootstrap. Do not inspect journal, mailbox, `routes.jsonl`, or `~/.collab`
+paths to prove registration. Missing or failed identity prevents claiming
+registration.
+
+If `collab context` explicitly reports daemon DOWN, a runtime error,
+`PROJECT_SCOPE_UNKNOWN`, or `token mismatch`, preserve the exact error and stop
+identity repair. Do not infer worktree scope from the error code alone, do not
+silently switch to a guessed parent or another project, and do not copy or edit
+identity/token state. If the snapshot shows a live master, report the exact
+context error to that master. If no live master exists, report it to the
+explicitly authorized migration/reset owner or the user. Do not re-register
+the worktree, start a daemon, reset the project, or promote a peer. Daemon
+lifecycle maintenance is human-authorized.
+
+See [`init-prompts.md`](init-prompts.md) for copy/paste master and peer
+initialization prompts.

package/skills/appsdk-project-governance/references/subagents-config.md

@@ -0,0 +1,134 @@
+# Persistent subworkers and shared policy
+
+This reference describes the persistent **subworker** policy. The `[subagent]`
+tables and `appsdk-subagent` MCP name are compatibility protocol tokens. They
+do not mean that Codex Desktop should use a native task/thread spawn command.
+
+Only `~/.appsdk/config.toml` owns startup/notification/timer policy. Run
+`appsdk config` from the project cwd to validate and inspect effective values.
+Global defaults work when the file is absent; project overrides stay in
+`[[projects]]` tables in that same file. Git worktrees inherit their main
+project's policy. Never copy Codex credentials or rewrite its profiles.
+
+```toml
+[notifications]
+enabled = true
+mode = "batch" # immediate or batch
+batch_window_seconds = 60
+transport = "appserver"
+submit_enter = true
+[notifications.events.deadline]
+mode = "immediate"
+[timers]
+enabled = true
+tick_interval_ms = 1000
+[keepalive]
+enabled = true
+interval_seconds = 900 # minimum 15 minutes
+max_unacked = 3 # legacy delivery throttle; recv consumes notifications
+[subagent]
+profile_priority = ["gcm", "oauth"]
+persistent = true
+close_on_task_complete = false
+[subagent.profiles.gcm]
+codex_profile = "gcm"
+[subagent.profiles.oauth]
+codex_profile = "oauth"
+model = "gpt-5.6-luna"
+[subagent.health]
+timeout_seconds = 45
+attempts_per_profile = 1
+expected_response = "OK"
+[subagent.startup]
+ready_timeout_seconds = 90
+# Optional:
+# [[projects]]
+# root = "/absolute/project/root"
+# [projects.notifications]
+# mode = "immediate"
+```
+
+Event keys: `direct_message`, `resource_released`, `deadline`;
+each accepts `mode = "inherit" | "immediate" | "batch"`. A fixed batch window
+does not slide when new messages arrive. Disabled timers suppress deadline
+notification generation, not task timeout safety checks. New subworkers read
+config at creation; existing daemons read policy at startup. Use controlled
+daemon restart after a policy change. Existing tasks/mailboxes remain intact.
+
+From a registered Codex App Server parent:
+
+```text
+appsdk subworker start --id <unique-request-id>
+appsdk subworker list
+appsdk subworker status <id>
+appsdk subworker snapshot <id> --lines 40
+appsdk subworker send <id> --subject <topic> "<task>"
+appsdk subworker close <id>
+```
+
+`start` probes each configured profile once, bounded by timeout, then launches
+one Codex session. Reusing an ID returns the existing record, never restarts
+it. `starting` is not `idle`: Codex may require trust/auth/approval interaction.
+Use status; do not inject automatic confirmation or keep re-sending tasks.
+All profiles failing returns a failed record with reasons and no launch.
+
+An already trusted cwd and healthy authenticated profile should start without
+new trust/auth interaction. Repeated prompts on that path are a startup bug,
+not an instruction to reinitialize credentials or accept prompts automatically.
+
+## Finite task keepalive and observation
+
+`send` creates the canonical `task-<message-id>` task in the Collab task list.
+Child `working` claims it; bind code work with `collab_task_relocate`, not a
+duplicate task registration. Complete the real task lifecycle; `ready` changes
+session availability only and never marks unfinished tasks complete.
+
+Unfinished actionable tasks are grouped by worker. Explicit idle for 15 minutes
+allows one activation. Read the notification with `collab recv`; reading consumes
+it atomically, so a normal follow-up ACK is not required. Messages sent by the
+worker and positive working observations count as activity. Unknown remains
+unknown; absent/unknown/working receive no activation. Blocked/waiting tasks
+follow their declared wait, not this continuation path.
+
+Three consecutive unconfirmed attempts exhaust the durable budget. After the
+third response window, status marks `suspected_offline`; it does not claim the
+process is dead. Failed/uncertain sends count, restart does not reset the budget,
+and no process is respawned. Only an explicit parent/operator request may use
+`appsdk subworker rearm <id>`; never rearm automatically to bypass exhaustion.
+
+`status` returns observed state, task list, parent mailbox, keepalive counters
+and notification/ACK history. `snapshot` is optional diagnostic output only;
+it never sends a notice or becomes task/control truth. Snapshot may contain
+sensitive output: request only when relevant, do not republish it by default.
+
+An agent without a live App Server native thread may use local project
+`list/status/snapshot` without registering a fake peer. Initialization and
+queries explicitly report `notification_channel: none`: no push channel exists
+for that observer. Check the mailbox in `status` yourself; do not wait for an
+automatic completion notification. This is not a quality gate or a reason to
+stop independent work. Mutating parent operations retain authenticated
+ownership checks.
+
+The child uses the injected `appsdk-subagent` MCP: `collab_init`, then
+`collab_subagent` with `action=ready, id=<id>`. The launcher forwards the live
+Codex App Server native-thread binding automatically; do not ask the user to
+set environment variables. Use MCP, not sandboxed shell registration. Only its
+bound identity may report ready. It accepts a dispatched task with `action=working`, manages its
+own task/worktree lifecycle, sends results to the parent, and calls `ready`
+when done. Repeated idle reports are no-ops. Remain idle, not an ACK/poll loop.
+Task progress stays in Collab task records; no second task queue exists here.
+Before assigned execution, use the same `appsdk bug intake --input <json>`
+contract or the parent's returned `issue_id`; no ID means no governed
+completion claim. Read-only conversation stays outside intake.
+
+Only the creating parent may send/close; a user-requested early close may
+interrupt work, but never deletes worktrees or marks tasks complete. Closing
+uses the exact registered peer identity. It does not stop the project daemon.
+Daemon restart replays records without automatically respawning or redispatching.
+If startup was interrupted, preserve the record/session and inspect status;
+do not reuse its ID to create another process.
+
+Upgrade: install reviewed Collab and AppSDK releases, then `collab down` /
+`collab up` per already-running project. No migration/reset/init of old tasks
+is required. Preserve journals and running subworker sessions. Do not downgrade
+to an older reader after new subworker events have been written to the journal.

package/skills/project-memory/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: project-memory
+description: "本地记忆: L1锚点+L2/L3入口+tag+相对路径; SQLite 搜 raw memory; 不是开发或规则升级门禁。"
+---
+
+# Project memory
+
+Use the independent `project-memory` command for memory only. It is available
+at any time and is not a debug/develop or AppSDK rule-upgrade gate.
+
+`memory/index.md` is the generated local index and curation source. It includes
+short titles, tags, relative detail paths, and a fixed-size Skill description
+candidate section. New details live in `memory/L1/`, `memory/L2/`, or
+`memory/L3/`. Raw entries remain in
+`memory/{plan,path,knowledge,lesson}.jsonl`; agents may read those Markdown and
+raw files directly.
+
+The project Skill `description` is the agent-visible resident index. During
+initialization or an intentional refresh, carry the generated candidate lines
+into that description manually: keep deduplicated level-1 anchors first, then
+fill unused base slots with level 2 and finally level 3 entries. Each L2/L3
+line states its kind, tags, and relative detail path. Do not invent paths or
+rewrite Skill text during an ordinary memory write. Legacy `memory/details/`
+remains readable for import compatibility but is not a new output location.
+
+## Review levels
+
+- New CLI entries default to level 3 (`unreviewed`).
+- Level 2 is reviewed and reusable; level 1 is reviewed and critical.
+- Only a real review with evidence may promote an entry. Use `promote` or a
+  run-note `memory_review`; ordinary writes cannot self-assign level 1/2.
+- Categories (`plan`, `path`, `knowledge`, `lesson`) describe content, not
+  review level. Tags are retrieval/classification features; one entry may have
+  multiple tags.
+
+Classify every durable entry as exactly one of:
+
+- `plan`: project goal, architecture, owner, boundaries, constraints.
+- `path`: node, edge, flow, checklist, or execution rule.
+- `knowledge`: one discrete fact, contract, function, resource, or setting.
+- `lesson`: verified historical experience, root cause, pitfall, or resolution.
+
+## Fixed query order
+
+Keep result groups in this order: L1 anchors, exact ID, node/function/resource,
+category/tag, declared relations, lesson references, FTS5 keywords, WeMM
+semantic candidates, then importance and updated time. Semantic candidates are
+advisory and never change explicit flow edges or active process revisions.
+
+## Commands
+
+```text
+project-memory query <text> [project]
+project-memory get <memory-id> [project]
+project-memory entry --title <title> --text <content> [--tag <tag>]
+project-memory entry --id <id> --category <category> --title <title> --text <content> [--tag <tag>]
+project-memory query --tag <tag> [text] [project]
+project-memory review --run <run-id>
+project-memory promote --id <id> --level <1|2> --evidence <ref>
+project-memory migrate [project]
+project-memory import [project] [--global]
+project-memory reentry [project] --run <run-id>
+project-memory index
+project-memory export
+project-memory compact
+project-memory verify
+```
+
+The title+content `entry` path is the one-shot writer: one invocation appends
+the raw event, atomically regenerates its detail Markdown, updates the title
+index, and rebuilds the SQLite projection. It defaults to level 3 and is
+idempotent by generated ID. Do not write raw, detail, or index files separately
+for a normal entry. If a projection step is interrupted, rerun `index`/`export`
+instead of submitting the entry again.
+`review` is the task-end write-back path. It checks run notes, deduplicates,
+classifies, preserves source references and tag unions, and updates the
+rebuildable index. A review without an evidence-backed `memory_review` remains
+level 3. Global promotion is explicit (`--global` on an entry); a project
+review never writes global memory.
+
+`compact` only compacts the rebuildable projection. It never rewrites, deletes,
+or drops events from the JSONL sources. The effective node is the last event
+for an ID with monotonic tag/source-reference/relation unions; changing an ID
+across categories is rejected.
+
+`index`/`export` is the raw-to-Markdown compatibility bridge: it regenerates
+`memory/index.md` and level-specific detail files without deleting or rewriting
+JSONL. `import` is the reverse bridge for an intentionally edited exported
+detail. It accepts only the marked AppSDK Markdown format (and the previous
+exported detail format), validates all detail files first, appends changed
+entries to the categorized JSONL source, and rebuilds the index. Repeating it
+without a Markdown change is a no-op. A detail is not a second truth store:
+the JSONL event history remains canonical, and direct Markdown edits
+to existing IDs take effect through explicit `import`.
+
+### Handwritten L3 additions (automatic)
+
+Write `memory/L3/<id>.md` using this format; filename and metadata ID must match:
+
+```markdown
+<!-- project-memory:v1 {"id":"cache-key-rule","category":"knowledge","tags":["cache","debug"]} -->
+
+# Cache keys include tenant
+
+Include the tenant ID in cache keys to isolate tenant data.
+<!-- project-memory:end -->
+```
+
+The next `query`, `get`, `index`, `export`, or `verify` imports new IDs into
+JSONL and SQLite automatically, even when SQLite already exists. No daemon,
+separate registration, or explicit import is needed for additions. Projection
+rebuilds also ingest pending additions before exporting. Repeated access adds
+no duplicate event. New entries are always L3/unreviewed; handwritten review
+claims are ignored. Missing category defaults to `knowledge`.
+
+For an existing ID, use `import` immediately after editing and before any
+projection rebuild. Automatic ingestion is additions-only, not conflict
+resolution between an edited detail and raw history. Invalid files fail with
+an actionable error and remain on disk; repair their format, do not delete
+memory to make a query pass. New L1/L2 files are not automatically ingested.
+
+Compatibility paths:
+
+```text
+legacy entries.jsonl/memories.jsonl --migrate--> categorized JSONL
+categorized JSONL --index|export--> index.md + L1/L2/L3/<id>.md
+edited marked detail --import--> categorized JSONL event + rebuilt projection
+```
+
+Malformed, unmarked, duplicate-ID, or conflicting details fail explicitly;
+they are never guessed into memory. `import --global` applies the same rule to
+the global detail directory.
+
+## Migration and re-entry
+
+Migration is explicit and source-preserving. `project-memory migrate` accepts
+the supported legacy flat sources (`memory/entries.jsonl` or
+`memory/memories.jsonl`), validates every line before writing, records a
+versioned `memory/migration.json` marker, appends new entries or
+metadata-completing events when the effective version lacks incoming tags or
+source references, and rebuilds the SQLite projection. The legacy source is
+never deleted or overwritten. A marker in `in_progress` can be run again with
+the same source digest; completed migration is idempotent. A changed source or
+an ID/content conflict is reported instead of silently replacing project
+truth.
+
+Re-entry may ingest new L3 details when it reads memory and rebuild stale or
+missing SQLite projections. Run
+`project-memory reentry [project] --run <run-id>` after an interruption (the
+project path is optional and may also follow the `--run` value). It keeps the
+same run ID, reads the last note as `resume_from`, checks the migration marker,
+rebuilds a missing index, and returns L1 anchors plus bounded `next_queries`
+for the next L2/L3 lookup. If migration is absent or unfinished, re-entry is
+blocked with the exact migration command; it never invents a new run or state.
+
+The WeMM adapter is optional. Until a pinned local inference backend is
+configured, it reports candidate-only RAG/semantic candidates and does not mock
+semantic edges. Graph search uses declared and semantic relation edges returned
+by `query`. Open the returned `detail_path` directly when the title is relevant;
+do not copy full detail into the index.