feat(#577): skill ownership + lifecycle model (P1)

[Weegy]

Summary

Phase 1 of #577 (skills as scope-owned, shareable artifacts). Adds the model layer only: ownership, a lifecycle state machine, and HMAC tamper-evidence over a canonical manifest. No resolution/shadowing (P2), no sharing/promotion/cron-guard (P3), no admin UI (P4) — those are separate, stacked phase PRs per the phase cut in docs/plans/phase4a-577-skills-prompt-2026-08-20.md.

Base: origin/main @ 28be3dde (merged in before this commit). This PR's own base branch: main.

What's in this PR

• Migration middleware/migrations/0040_skill_ownership_lifecycle.sql (next free number — 0038 is reserved for the Satellites epic Epic: Satellites — outbound-only edge nodes (Raspberry Pi class) that pair with a device code, run selected agents, and bridge internal-only systems securely into the main omadia #746, 0039 is turn_receipts, both already on main). Adds four nullable/defaulted columns to the existing skills table (from 0003_agent_builder_graph.sql, the table skillImport.ts/skillLoader.ts/skillGuard.ts already operate on):
  • owner_scope TEXT — the skill's home as a ScopeId wire string (personal:<userId> / group:<groupRef> / org:<orgId>). Nullable: pre-existing imported rows predate ownership and stay unowned until assigned, same posture as content_hash in 0004.
  • lifecycle_status TEXT NOT NULL DEFAULT 'draft' with a CHECK constraint for draft/reviewed/published/archived.
  • manifest_signature TEXT, manifest_signed_at TIMESTAMPTZ — HMAC tamper-evidence, NULL until first signed transition.
• src/services/skillLifecycle.ts — pure, synchronous model:
  • SkillOwnerScope narrows ScopeId (@omadia/channel-sdk, Scope model with audience-floor permission intersection for shared rooms #575) to personal | group | org — a skill cannot be owned by a conversation/system/unscoped scope.
  • SKILL_LIFECYCLE_EDGES — explicit allowlist of legal transitions (draft→reviewed, reviewed→draft, reviewed→published, published→archived). archived is terminal; every other pair (including same-status) is illegal.
  • requiredCapabilitiesFromFrontmatter — reads frontmatter.requiredCapabilities. Absent → []. Malformed (not an array, or a non-string/blank entry) → throws SkillManifestError naming the exact field/index/value. Never silently drops — the fix(skills): surface frontmatter the SKILL.md import silently drops #690 lesson (frontmatter parser silently dropped data instead of erroring).
  • canonicalSkillManifest — the byte-exact serialization that gets signed: fixed field order (an array of pairs, not an object — immune to key-insertion-order), requiredCapabilities deduped + sorted by plain codepoint comparison (order-independent) but never case-folded (mirrors the feat(#333): Principal — the platform's typed answer to "who is this?" (phase 1) #724 precedent: role keys aren't lowercased because case is semantically significant; same rule applied to capability identifiers here).
  • signSkillManifest / verifySkillManifestSignature — HMAC-SHA256, constant-time compare, never throws on a malformed/wrong-length signature.
  • missingRequiredCapabilities / canPublishSkill — pure set-difference against an already-resolved granted set. Deliberately has no dependency on GrantStore — P3 (sharing + promotion) is the one place that resolves how a capability got granted; this module only checks whether it's present.
  • transitionSkillLifecycle — combines all three P1 invariants (legal move, valid owner scope, publish capability gate) into one pure decision, re-signing the manifest at the new status on success.
• src/services/skillLifecycleStore.ts — thin Postgres store over the new columns (getSkill, assignPersonalOwner, transition), using raw pool.query rather than a new AgentGraphStore method — keeps this phase's surface to src/services/skill* per the binding surface separation with the parallel Credential keychain with grants and a broker that keeps secrets away from the agent #578 session. assignPersonalOwner is the only direct-assignment path (personal only): Skills as scope-owned, shareable artifacts (grants, org promotion, git skill packs) #577's Kernkonzept explicitly forbids creating a skill directly in team/org scope — those are reached only through admin-gated promotion (P3).
• Tests: test/skillLifecycle.test.ts (30 cases, pure) + test/skillOwnershipLifecycleStore.pg.test.ts (6 cases, pg-gated, new file — kept separate from the pre-existing skillLifecycleStore.pg.test.ts which covers unrelated Wave-0 content_hash/forkedFrom coverage on AgentGraphStore, so fixtures never collide).

Blast radius

• New columns only, all nullable/defaulted — no existing read path touches them, no existing write path is required to set them. Zero behavior change for the current skill-import/guard/loader pipeline.
• No existing file touched — this PR is 5 new files, 0 diffs to existing code. skillImport.ts, skillGuard.ts, skillLoader.ts, agentGraphStore.ts, grants.ts, admin.ts are all untouched, consistent with the binding surface separation.
• @omadia/channel-sdk consumed only (ScopeId, parseSessionScope, formatSessionScope) — no edits to that package.
• Full middleware suite: 6915 tests / 6903 pass / 0 fail / 12 pre-existing skips (unrelated) after this change, both before and after origin/main merge + rebuild.

Test + mutation evidence

Ran the full non-pg suite (npm test) and the pg-gated suite for skills against an ephemeral local Postgres — all green, no regressions in the pre-existing skillLifecycleStore.pg.test.ts / skillImport.test.ts / skillHash.test.ts / skillGuard.test.ts.

Manual mutation checks against skillLifecycle.ts (rebuilding nothing extra was needed — these are pure functions run directly via tsx, no dist/ involved; the pg-gated store test was separately verified to exercise the compiled migration against real Postgres):

#	Mutation	Result
1	Added archived → draft as a legal edge (reopen the terminal state)	2 tests fail: the full 4×4 matrix test and the explicit "archived is terminal" test
2	Lowercased capabilities before sorting in canonicalSkillManifest (case-fold, breaking the #724 precedent)	1 test fails: "does NOT case-fold capabilities"
3	Made requiredCapabilitiesFromFrontmatter silently skip invalid entries instead of throwing (reintroducing the #690 defect shape)	2 tests fail: the index-naming and blank-string error-message tests
4	Disabled the publish capability gate entirely (if (false && target === 'published'))	1 test fails: "blocks publish when a required capability is not granted"

All four mutations were reverted after confirming failure; the working tree is clean (git diff --stat on the mutated file shows no residue).

Not in this PR (later #577 phases)

• Wiring owner_scope assignment into the existing importSkillMarkdown create path (P2/P3 — a scope-aware import flow).
• Scope-ordered resolution + shadowing in skillLoader.ts (P2).
• GrantStore-backed capability resolution, sharing grants, admin-gated org/team promotion, cron write-guard (P3).
• Any HTTP route or web-ui surface (P4).

Migration number

0040. Verified against origin/main @ merge time: 0038 reserved (#746 Satellites), 0039 is turn_receipts (#757), nothing else claims 0040. The parallel #578 (Keychain) session works in credentials//vault surfaces per the binding separation and should not need this series.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}