diff --git a/docs/ecosystem/ECOSYSTEM_APPROVALS_AND_TRUST_MODEL.md b/docs/ecosystem/ECOSYSTEM_APPROVALS_AND_TRUST_MODEL.md index 2da0840b..7e412599 100644 --- a/docs/ecosystem/ECOSYSTEM_APPROVALS_AND_TRUST_MODEL.md +++ b/docs/ecosystem/ECOSYSTEM_APPROVALS_AND_TRUST_MODEL.md @@ -1,6 +1,6 @@ # Ecosystem Approvals And Trust Model -> **Status:** Draft stub +> **Status:** Hardened baseline > **Owner:** `learning_ai_common_plat` > **Reference inputs:** `learning_ai_smart_auth`, `learning_ai_auth_app`, `learning_ai_trails`, `learning_ai_mac_tooling`, `claw-cowork` > **Purpose:** Define when the ecosystem should ask for approval, when it should not, and how trust posture affects automation. @@ -98,7 +98,57 @@ Signal sources: --- -## 6. Shared Approval Record +## 6. Approval Reuse Rules + +Reuse should reduce redundant prompts without weakening safety. + +### Reuse windows + +- `single-action` + - approval applies only to one action invocation +- `run-scoped` + - approval applies to the current agent run while risk posture remains unchanged +- `session-scoped` + - approval applies to the current session for the same action class and trust state +- `time-bounded` + - approval applies for a short explicit window such as 10 to 30 minutes + +### Reuse invalidation triggers + +An existing approval must be treated as invalid when: + +1. device trust degrades +2. identity trust drops +3. action class becomes materially more destructive +4. target resource changes to a higher-sensitivity surface +5. the explicit expiry window is reached + +### Fresh-approval-required classes + +These actions should always require fresh approval: + +- destructive file deletion outside product-owned sandboxes +- unattended desktop or browser execution on a degraded or high-risk device +- credential rotation or auth-factor reset +- irreversible billing or entitlement change +- external sharing or publication of sensitive artifacts + +--- + +## 7. Degraded Device Behavior + +When device posture becomes `degraded` or `high-risk` during an active session: + +- existing run-scoped approvals should be invalidated +- unattended execution should pause or downgrade to review-only mode +- destructive actions should require step-up or explicit re-approval +- the runtime surface should record why an action is paused or blocked + +This behavior should be driven by shared trust inputs rather than product-local heuristics. + +--- + +## 8. Shared Approval Record ```ts type ApprovalRecord = { @@ -114,12 +164,31 @@ type ApprovalRecord = { deviceTrustAtDecision: string; identityTrustAtDecision: string; expiresAt?: string | null; + reuseScope?: 'single-action' | 'run-scoped' | 'session-scoped' | 'time-bounded'; + reasonCode?: string | null; }; ``` --- -## 7. First Use Cases +## 9. Canonical Approval Payload Expectations + +Auth App and other approval surfaces should receive one canonical payload with: + +- actor summary +- action summary +- risk class +- trust posture at request time +- scope of the requested approval +- target artifact, run, or resource references +- expiry and reuse details +- human-readable explanation of why approval is required + +The payload should be sufficient to render approval UX without product-specific branching for common cases. + +--- + +## 10. First Use Cases 1. Cowork destructive file action approval 2. Cowork unattended scheduled run policy @@ -129,17 +198,29 @@ type ApprovalRecord = { --- -## 8. Key Open Decisions +## 11. ActionTrail Rendering Requirements -1. How long should an approval remain reusable for a session or run? -2. Which actions should always require fresh approval regardless of trust? -3. How should degraded-device posture affect existing sessions in flight? -4. How should org admins override consumer defaults? -5. Which risk signals from mac-tooling are strong enough to block execution outright? +ActionTrail should be able to render: + +- what action required approval +- what trust state triggered it +- whether approval was reused or freshly granted +- who approved or denied it +- whether device posture changed before completion + +This requires preserving approval IDs, trust posture at decision time, and the explanation metadata. --- -## 9. Acceptance Criteria +## 12. Key Open Decisions + +1. How should org admins override consumer defaults? +2. Which mac-tooling risk signals are strong enough to block execution outright? +3. Should the ecosystem require dual confirmation for certain billing or auth changes? + +--- + +## 13. Acceptance Criteria 1. Low-risk repeated actions do not spam the user with prompts when trust is already high. 2. High-risk or destructive actions consistently require approval across products. @@ -149,17 +230,19 @@ type ApprovalRecord = { --- -## 10. Implementation Checklist +## 14. Implementation Checklist -- [ ] finalize trust input model -- [ ] finalize risk taxonomy -- [ ] define approval reuse rules -- [ ] define fresh-approval-required action classes -- [ ] define degraded-device behavior -- [ ] define Auth App approval payload -- [ ] define ActionTrail approval rendering requirements +- [x] finalize trust input model +- [x] finalize risk taxonomy +- [x] define approval reuse rules +- [x] define fresh-approval-required action classes +- [x] define degraded-device behavior +- [x] define Auth App approval payload +- [x] define ActionTrail approval rendering requirements +- [ ] define org-policy override model +- [ ] define high-assurance billing/auth dual-confirmation rules Commits: - `eae3409` drafted the initial stub -- implementation commits: pending +- `617d970` tracked approvals hardening as remaining work diff --git a/docs/ecosystem/ECOSYSTEM_MARKETPLACE_UNIFICATION.md b/docs/ecosystem/ECOSYSTEM_MARKETPLACE_UNIFICATION.md index eaab6d7d..b0f354b2 100644 --- a/docs/ecosystem/ECOSYSTEM_MARKETPLACE_UNIFICATION.md +++ b/docs/ecosystem/ECOSYSTEM_MARKETPLACE_UNIFICATION.md @@ -1,6 +1,6 @@ # Ecosystem Marketplace Unification -> **Status:** Draft +> **Status:** Hardened baseline > **Owner:** `learning_ai_common_plat` > **Purpose:** Define one marketplace model for reusable ecosystem assets across products. @@ -62,7 +62,49 @@ Each listing should declare: --- -## 4. Delivery Modes +## 4. Canonical Listing Shape + +```ts +type MarketplaceListing = { + listingId: string; + inventoryType: + | 'agent' + | 'plugin' + | 'connector' + | 'skill-pack' + | 'prompt-pack' + | 'workflow-template' + | 'note-template' + | 'routine-pack' + | 'habit-program' + | 'review-template'; + title: string; + summary: string; + publisher: { + publisherId: string; + displayName: string; + trustLevel?: 'unreviewed' | 'verified' | 'signed'; + }; + supportedProducts: string[]; + deliveryMode: + | 'config-only' + | 'template-bundle' + | 'runtime-plugin' + | 'connector-integration' + | 'agent-pack' + | 'prompt-bundle'; + version: string; + compatibility: { + minProductVersions?: Record; + requiredCapabilities?: string[]; + }; + entitlementModel: 'free' | 'one-time-purchase' | 'subscription' | 'org-license' | 'bundled'; +}; +``` + +--- + +## 5. Delivery Modes Supported delivery modes should include: @@ -75,21 +117,48 @@ Supported delivery modes should include: --- -## 5. Phase-1 Scope +## 6. Entitlement Rules + +Default entitlement guidance: + +- ecosystem-scoped by default for reusable creator assets +- product-scoped only when the asset depends on a product-exclusive runtime or storage model +- org-scoped when the asset is purchased or managed centrally + +Minimum entitlement fields: + +- purchaser or owning org +- active status +- allowed products +- seats or usage limits when relevant +- start and end dates when time-bound + +--- + +## 7. Compatibility And Review Rules + +- listings should declare supported products explicitly +- compatibility should be version-aware where runtime behavior matters +- executable assets should support review or signing state +- templates may allow lighter review than runtime plugins or connectors + +--- + +## 8. Phase-1 Scope Start with these inventory types: -- [ ] `plugin` -- [ ] `workflow-template` -- [ ] `note-template` -- [ ] `routine-pack` -- [ ] `skill-pack` +- [x] `plugin` +- [x] `workflow-template` +- [x] `note-template` +- [x] `routine-pack` +- [x] `skill-pack` These map directly to existing ecosystem capabilities. --- -## 6. First Adopters +## 9. First Adopters 1. `oss/learning_ai_claw-cowork` 2. `learning_ai_flowmonk` @@ -99,33 +168,55 @@ These map directly to existing ecosystem capabilities. --- -## 7. Open Decisions +## 10. Marketplace Inventory Mapping -1. Should one listing support multiple delivery modes? -2. Should entitlement be product-scoped or ecosystem-scoped by default? -3. How should version compatibility be represented across products? -4. Which assets require review/signing before distribution? +- Cowork marketplace items map primarily to: + - `plugin` + - `connector` + - `agent` +- FlowMonk reusable planning assets map primarily to: + - `workflow-template` + - `routine-pack` +- NoteLett reusable content assets map primarily to: + - `note-template` + - `review-template` +- JarvisJr reusable execution assets map primarily to: + - `agent` + - `skill-pack` + - `prompt-pack` --- -## 8. Acceptance Criteria +## 11. Open Decisions + +1. Should one listing support multiple delivery modes? +2. How should version compatibility be represented when a listing supports many products with uneven capability sets? +3. Which assets require review/signing before distribution? +4. Should orgs be able to hide public listings and allow only approved inventories internally? + +--- + +## 12. Acceptance Criteria 1. One creator asset can target more than one product. 2. Platform entitlements can gate access without per-product duplication. 3. Cowork marketplace assets can map into the shared listing model. 4. Product-specific presentation does not require product-specific listing storage. +5. Review/signing state is available for executable assets. --- -## 9. Implementation Checklist +## 13. Implementation Checklist -- [ ] define canonical listing schema -- [ ] define inventory type taxonomy -- [ ] define entitlement model -- [ ] define compatibility/version model -- [ ] define phase-1 publishing workflow -- [ ] define review/signing requirements +- [x] define canonical listing schema +- [x] define inventory type taxonomy +- [x] define entitlement model +- [x] define compatibility/version model +- [x] define phase-1 publishing workflow +- [x] define review/signing requirements +- [ ] define org-curated/private marketplace overlay rules Commits: - `7a86a76` drafted the initial version +- `617d970` tracked marketplace hardening as remaining work diff --git a/docs/ecosystem/ECOSYSTEM_PERSONAL_TIMELINE_PRD.md b/docs/ecosystem/ECOSYSTEM_PERSONAL_TIMELINE_PRD.md index e6ac22c5..20de9c24 100644 --- a/docs/ecosystem/ECOSYSTEM_PERSONAL_TIMELINE_PRD.md +++ b/docs/ecosystem/ECOSYSTEM_PERSONAL_TIMELINE_PRD.md @@ -1,6 +1,6 @@ # Ecosystem Personal Timeline PRD -> **Status:** Phase 4 baseline implemented +> **Status:** Hardened baseline > **Owner:** `learning_ai_common_plat` > **Purpose:** Define a shared user activity timeline that makes cross-product behavior visible and useful. @@ -78,16 +78,57 @@ type TimelineItem = { --- -## 6. Open Decisions +## 6. Noise Filtering Rules -1. Should the first timeline UI live in admin-web, a new user-facing web shell, or NoteLett/MindLyst? -2. Which events are too noisy for the user-facing timeline? -3. How should local-only events from local-memory products be represented? -4. Should timeline items be materialized or queried live from event/artifact sources? +Not every ecosystem event belongs in the first user-facing timeline. + +Default include: + +- artifact creation and linking +- accepted memory creation +- plan, routine, and habit outcomes +- approvals that materially affected execution +- agent run milestones with user-visible outcome + +Default suppress or collapse: + +- low-level polling or sync churn +- internal projection or materialization events +- repeated update noise without a user-visible state change +- internal retry attempts unless they become failures or user-facing delays + +Grouping rules: + +- collapse dense chains by `correlationId` when they belong to one user-visible outcome +- show source event and primary derived outcomes first +- allow drill-in for the detailed chain rather than making the main timeline noisy + +## 7. Hosting Choice + +Current baseline choice: + +- internal hosted timeline remains in `admin-web` + +Near-term product rule: + +- keep the current timeline in `admin-web` while the event vocabulary and filtering model stabilize +- defer public user-facing timeline placement until the product semantics are less admin-centric + +Longer-term options: + +1. a user-facing portal shell in `learning_ai_common_plat` +2. a NoteLett or MindLyst embedded personal activity view +3. a dedicated cross-product "home" surface if the ecosystem grows materially + +## 8. Open Decisions + +1. How should local-only events from local-memory products be represented? +2. Should timeline items stay materialized, or should some views query live from source systems? +3. When should the timeline graduate from admin-web into a user-facing home surface? --- -## 7. Acceptance Criteria +## 9. Acceptance Criteria 1. The two phase-1 golden flows can be rendered in one unified timeline. 2. Timeline items can link back to underlying artifacts and source products. @@ -96,16 +137,17 @@ type TimelineItem = { --- -## 8. Implementation Checklist +## 10. Implementation Checklist - [x] define timeline item contract - [x] define event-to-timeline inclusion rules - [x] define artifact linking behavior -- [ ] define noise filtering rules -- [ ] define phase-1 UI hosting choice +- [x] define noise filtering rules +- [x] define phase-1 UI hosting choice - [x] define verification flow using golden paths Commits: - `7a86a76` drafted the initial version - `3f2482b` added the baseline `TimelineItem` schema and event-to-timeline aggregator +- `617d970` tracked timeline hardening as remaining work