@moretea-labs/forge 1.6.0 → 1.7.1

package/docs/architecture/current/verification-and-release-gates.md

@@ -1,391 +0,0 @@
-# Verification and Release Gates
-
-> Status: **Runtime Authority**
-
-## 1. Objective
-
-Verification determines whether evidence satisfies a declared contract for an exact repository state. Release gating determines whether the repository is ready for an externally visible delivery action.
-
-The system distinguishes:
-
-```text
-execution success
-integration success
-verification success
-Task acceptance
-Issue completion
-release readiness
-release execution
-```
-
-No step implies the next without its required evidence.
-
-## 2. Evidence Principles
-
-Evidence must be:
-
-- generated by the Controller or a trusted repository system;
-- bound to stable repository and checkout identity;
-- bound to an exact Revision or artifact hash;
-- addressable through a durable artifact reference;
-- bounded when returned to clients;
-- honest about failure, timeout, truncation, or missing data;
-- reusable only while its cache/precondition contract remains valid.
-
-Worker or Agent prose is supplementary evidence, not authoritative pass/fail proof.
-
-## 3. Verification Record
-
-A Verification Record contains:
-
-```text
-repoId
-checkoutId
-revision
-issueId / taskId
-runId / editSessionId / integrationId
-reviewedDiffHash
-checkResults
-commandEvidence
-acceptanceResults
-reviewer
-verifiedAt
-environmentFingerprint
-artifact references
-staleAt / staleReason when invalidated
-```
-
-A caller cannot satisfy required named checks by reporting `ok: true`. The Controller executes the check or verifies a trusted external artifact.
-
-## 4. Exact Revision
-
-Verification applies to one Revision definition, normally derived from:
-
-```text
-HEAD
-tracked working-tree diff
-relevant untracked files
-check configuration
-environment fingerprint
-```
-
-The Revision contract excludes known runtime-only evidence directories.
-
-If relevant files change after verification:
-
-- the previous record remains historical;
-- completion logic treats it as stale;
-- required verification runs again for the new Revision.
-
-## 5. Verification Layers
-
-### Layer 1 — Patch Integrity
-
-For Direct Edit or integration:
-
-- allowed paths respected;
-- before/after hashes recorded;
-- diff is available;
-- change budget respected;
-- no unsupported binary/rename behavior hidden;
-- user changes outside scope preserved.
-
-### Layer 2 — Focused Checks
-
-Run the smallest deterministic checks that directly cover the change.
-
-Examples:
-
-- one test file;
-- one package type check;
-- one domain test suite;
-- one architecture or documentation gate.
-
-### Layer 3 — Task Contract
-
-Evaluate all Task-declared checks and acceptance criteria.
-
-Acceptance criteria must be observable and must not merely repeat “implementation complete.”
-
-### Layer 4 — Integration Verification
-
-After an isolated Run is integrated:
-
-- verify target Revision, not only Worktree Revision;
-- verify integration record and reviewed diff hash;
-- rerun affected checks when target state changed;
-- retain Worktree until durable integration outcome exists.
-
-### Layer 5 — Issue or System Integration
-
-Run broader checks required by the Issue, architecture boundary, or affected runtime subsystem.
-
-### Layer 6 — Release Gate
-
-Run release-specific checks against a frozen candidate Revision.
-
-## 6. Risk-Adaptive Verification
-
-### Read-only
-
-Requires evidence of the requested observation. No diff gate.
-
-### Low-risk change
-
-Focused checks when declared; may auto-complete after successful applicable evidence.
-
-### Medium-risk change
-
-Declared checks and acceptance evidence apply. Auto-completion is allowed only when policy says no human decision is required.
-
-### High-risk change
-
-Requires:
-
-- reviewed diff or integrated Revision;
-- required verification evidence;
-- acceptance criteria results;
-- explicit human acceptance.
-
-### Destructive change
-
-Requires all high-risk evidence plus explicit same-request destructive authorization and operation-specific safety/rollback plan.
-
-## 7. Task Acceptance
-
-Task acceptance occurs after verification policy passes.
-
-Acceptance action records:
-
-```text
-acceptedBy
-acceptedAt
-verificationId
-revision
-note
-```
-
-Dependent Tasks unlock only from accepted terminal semantics, not from a successful Run alone.
-
-For eligible low/medium-risk work, Controller policy may auto-accept and records that automation explicitly.
-
-## 8. Failed Verification
-
-A real failed check or acceptance criterion moves work to `changes_requested` or a similarly explicit corrective state.
-
-Failure handling:
-
-1. preserve check output and artifact;
-2. classify failure as introduced, pre-existing, environmental, flaky, stale, or contract-related;
-3. avoid claiming unrelated pre-existing failure was caused or fixed;
-4. create a focused correction or blocker;
-5. rerun only the necessary evidence after the Revision changes.
-
-A flaky check requires explicit flake evidence and retry policy. Repeating until green without recording attempts is forbidden.
-
-## 9. Shared Check Evidence
-
-Identical check requests may share one execution when these match:
-
-```text
-repoId
-checkoutId
-checkId
-revision
-timeout contract
-environment fingerprint
-```
-
-Every subscriber links to the same immutable evidence. One subscriber cancellation must not terminate execution required by others.
-
-## 10. Release Readiness
-
-A repository is `release_ready` only when all required conditions are true for the candidate Revision.
-
-Baseline gate:
-
-```text
-repository identity valid
-remote/GitHub mapping diagnosed
-candidate Revision fixed
-Workspace ownership known
-no active write Job
-no active Agent Run
-no pending integration
-no unresolved integration conflict
-no dirty Edit Session
-no orphan/unknown execution affecting candidate
-required Tasks accepted
-required checks pass for candidate Revision
-architecture/document gates pass
-package/public metadata valid
-release manifest generated
-rollback or recovery plan recorded when required
-human authorization boundary identified
-```
-
-A project may add stricter repository-specific gates.
-
-## 11. Release Freeze
-
-Before final release verification, the Repo Actor acquires an exclusive release Claim and enters Release Freeze.
-
-During freeze:
-
-- new mutation Jobs wait;
-- active writers finish or are explicitly resolved;
-- Integration Queue drains;
-- read-only inspection continues;
-- release checks run against the fixed candidate;
-- Schedule mutation work pauses;
-- any relevant file change invalidates the candidate and requires a new gate.
-
-Release Freeze is released after:
-
-- release execution completes;
-- release is cancelled;
-- verification fails and the candidate returns to development;
-- Lease expires and recovery reconciles state.
-
-## 12. Release Manifest
-
-The release gate produces a durable manifest:
-
-```text
-repoId
-checkoutId
-candidateRevision
-branch
-target version or release identifier
-included Issues and Tasks
-verification records
-check artifact hashes
-known warnings
-known non-blocking pre-existing failures
-remote target
-release actions requiring authorization
-rollback/recovery instructions
-createdAt
-approvedBy / approvedAt when applicable
-```
-
-The manifest is an execution input and audit record. It does not execute release actions by itself.
-
-## 13. External Actions
-
-The following remain explicit external boundaries:
-
-- commit when user policy requires review;
-- push;
-- create/update remote PR when not already authorized by the Task;
-- merge;
-- tag;
-- package publication;
-- production deployment;
-- remote Issue closure;
-- destructive migration or data mutation.
-
-The Controller may prepare exact commands and evidence. It may execute only with explicit authorization appropriate to the operation.
-
-## 14. Release Job
-
-Release execution, when authorized, is a durable Job.
-
-It records:
-
-```text
-releaseManifestId
-requestId
-remote target
-operation sequence
-current step
-external identifiers
-stdout/stderr/artifacts
-partial outcome
-compensation or resume instructions
-```
-
-A disconnected client does not make external outcome unknown if provider or command evidence can prove it. Otherwise the Release Job becomes orphaned/unknown and requires reconciliation before retry.
-
-## 15. Partial Release
-
-Multi-step or multi-repository release may end partially complete.
-
-Partial outcome records:
-
-- completed external actions;
-- failed or unstarted actions;
-- current deployed/published versions;
-- safe compensation options;
-- actions that require human decision.
-
-The system must not collapse partial release into success or rerun all actions blindly.
-
-## 16. Rollback and Recovery
-
-Rollback is not assumed universally safe.
-
-A release plan declares one of:
-
-```text
-reversible with deterministic rollback
-forward-fix preferred
-feature-flag disable
-provider-native rollback
-manual recovery only
-```
-
-Rollback itself is externally visible/destructive work and requires appropriate authorization and evidence.
-
-## 17. Architecture Gate
-
-Architecture-sensitive releases must pass:
-
-- current architecture document presence;
-- Runtime Authority marker;
-- historical document marker policy;
-- architecture drift check;
-- relevant ADR linkage;
-- migration roadmap update when target gaps change.
-
-Architecture documentation is part of the release contract, not an optional afterthought.
-
-## 18. Verification Performance
-
-Verification must remain proportional:
-
-- focused checks during iteration;
-- Task checks before acceptance;
-- broader Issue/system checks at integration boundaries;
-- full release gate once the candidate is frozen.
-
-Running the full release suite after every small patch wastes resources and increases queue contention. Running only focused checks before release is insufficient.
-
-Check results and revision-aware caches prevent unnecessary duplication without hiding stale evidence.
-
-## 19. Current Implementation
-
-Verification evidence is bound to Job, repository and exact Git revision with an environment fingerprint. Revision changes invalidate reusable evidence. Oversized result bodies are stored as Artifacts and only bounded previews are returned through Job status.
-
-Release readiness is implemented as a durable `release-gate` Job holding an exclusive `release:<repoId>` Lease. The Gate checks Workspace cleanliness, active Execution Jobs, Agent Runs, Local compatibility Jobs, pending Worktree integration, unfinished Edit Sessions, other Leases, active-Issue Tasks, exact-revision verification, repository remote identity, GitHub mapping, Canonical Forge Runtime readiness and package metadata.
-
-A successful Gate returns a release manifest for the exact current revision. Push, merge, publish, deploy and destructive external operations still require a separate explicit user authorization.
-
-## 20. Required Release Tests
-
-Runtime and release checks cover:
-
-- candidate revision changes invalidate evidence;
-- active writers block release;
-- pending Worktree integration blocks release;
-- dirty Edit Sessions block release;
-- remote and GitHub mapping drift block release;
-- release Lease blocks new writes;
-- a successful Gate does not execute an external side effect;
-- partial external outcomes never become global success.
-
-## 21. Immutable Check Definition Snapshot
-
-A scheduled check stores the normalized command, cwd, timeout, source, registry revision, and definition digest at admission time. Execution validates the digest and repository-relative cwd, then uses that snapshot even if another checkout or a later commit changes the check registry.
-
-The snapshot stabilizes check identity; the produced evidence is still bound to the revision observed when execution starts and becomes stale if repository content changes while the command runs. This prevents both `check not found` after checkout switching and accidental reuse of evidence from a different repository revision.

package/docs/forge-autonomous-goal-loop.md

@@ -1,9 +0,0 @@
-# Forge Goal Loop
-
-Forge supports bounded goal progression through durable Goal, Work, Process, evidence, policy, and handoff records. The kernel does not recursively invent unlimited work, select arbitrary models, or bypass authorization. Semantic planning and provider selection belong to the external controller; deterministic repository and provider operations remain Forge-owned.
-
-Every continuation must have a finite objective, resource scope, budget, stop condition, and reviewable evidence. Remote or destructive effects stay separately authorized. A Schedule can wake an external Controller for an existing bounded Work; ChatGPT wakeups reuse a saved Forge browser session or explicit conversation URL when available, so conversation continuity is a transport concern rather than Kernel reasoning.
-The stable configuration path is `rh_work.schedule_*`: create one continuation policy for an already accepted Work, inspect it, pause/resume it, or trigger one bounded Occurrence. The engine re-checks Work terminality before launch and automatically disables the Schedule when the Work is complete, so users do not need to keep sending “continue” and Forge does not keep waking a model after acceptance is satisfied.
-A scheduled wake uses a short launch reservation rather than a fake Controller lease. The external model becomes owner only after its own authenticated MCP session calls `rh_work continue`; this is the identity handoff boundary between deterministic scheduling and semantic control.
-
-See [Dispatch and Agent Strategy](architecture/current/dispatch-and-agent-strategy.md), [Schedule Engine](architecture/current/automation-and-schedule-engine.md), and [Governance](architecture/current/governance.md).

package/docs/forge-provider-configuration.md

@@ -1,7 +0,0 @@
-# Forge Provider Configuration
-
-Forge keeps provider selection separate from Runtime ownership. Codex, Claude, GitHub, browser, Google Workspace, Apple, iOS, Desktop, and other adapters execute bounded contracts through stable Forge policy, Process, receipt, and audit layers.
-
-Provider credentials are supplied through supported environment or OS credential mechanisms and are never copied into repository state or chat output. Provider availability does not change the one-Runtime topology.
-
-See [Provider configuration](operations/provider-configuration.md), [Plugin baseline](architecture/current/personal-assistant-plugin-baseline.md), and [Security Model](wiki/Security-Model.md).

package/docs/operations/chatgpt-personal-assistant-runtime.md

@@ -1,93 +0,0 @@
-# ChatGPT-first Personal Assistant Runtime
-
-This runtime is designed for a local-first personal assistant where ChatGPT is the primary natural-language controller and Forge is the guarded local execution layer.
-
-## Product boundary
-
-The Local Controller should not be the main task input surface. It stores routines, inbox items, memory, approvals, audit events, device tokens, and plugin state. ChatGPT, MCP, or a GPT Action should translate natural language into one of the high-level assistant APIs.
-
-## High-level API surface
-
-Expose these endpoints to ChatGPT Actions instead of exposing every low-level plugin action:
-
-- `POST /api/assistant/intent` — submit a natural-language utterance or a ChatGPT-planned action list.
-- `GET /api/assistant/inbox` — read assistant outputs, routine results, and approval notes.
-- `GET /api/assistant/routines` — list saved routines.
-- `POST /api/assistant/routines` — create a routine from a natural-language goal.
-- `POST /api/assistant/routines/:routineId/run` — run one routine immediately.
-- `POST /api/assistant/routines/:routineId/pause` — pause a routine.
-- `POST /api/assistant/routines/:routineId/resume` — resume a routine.
-- `POST /api/assistant/routines/:routineId/delete` — soft-delete a routine.
-- `GET /api/assistant/memory` and `POST /api/assistant/memory` — read/write local preference memory.
-- `GET /api/assistant/openapi.json` — minimal OpenAPI schema for a Custom GPT Action.
-
-All `/api/*` routes still require the local controller token.
-
-## Intent modes
-
-`/api/assistant/intent` supports three modes:
-
-- `plan_only`: return the interpreted plan without submitting execution jobs.
-- `plan_then_execute`: plan and submit safe steps; block high-risk steps.
-- `execute`: submit the supplied plan directly through the same policy gate.
-
-The preferred ChatGPT flow is:
-
-1. ChatGPT understands the user request.
-2. ChatGPT asks for missing information or confirmation when needed.
-3. ChatGPT calls `/api/assistant/intent` with either the natural-language utterance or an explicit `plan`.
-4. Forge validates policy, creates durable Execution Jobs, stores an Assistant Inbox item, and returns display text.
-
-## Routine model
-
-A routine stores the user's natural-language goal rather than a traditional GUI rule form:
-
-```json
-{
-  "name": "每日邮件整理",
-  "naturalLanguageGoal": "每天早上 9 点整理过去 24 小时重要邮件，重点关注工作、API、BA、Jira、PR，用中文输出摘要。",
-  "scheduleText": "每天 09:00",
-  "dataSources": ["gmail", "calendar", "tasks"],
-  "output": "assistant_inbox",
-  "allowedActions": ["gmail.list_messages", "gmail.get_message"],
-  "forbiddenActions": ["gmail.send_message", "gmail.trash_message"]
-}
-```
-
-Routine execution and long-lived goal continuation use the existing Schedule Engine rather than a second assistant daemon. Semantic/model-backed routine logic remains external-controller-owned; the Kernel does not execute an unbounded model loop on a timer.
-
-For an accepted non-terminal Work, ChatGPT can create a bounded `rh_work.schedule_create` policy in one of three modes:
-
-- `continuation` — wake the bound ChatGPT/Codex/Claude/Grok Controller at the configured trigger;
-- `browser_watch` — silently refresh/read an allowed browser target, fingerprint a deterministic text projection, and wake the bound Controller only when the observation changes;
-- `browser_keepalive` — silently refresh an authenticated browser target and wake only when configured login markers indicate that user authentication is required.
-
-The first `browser_watch` observation is a silent baseline by default. Unchanged observations do not create a ChatGPT conversation turn. When the bound Work becomes terminal, Forge disables the Schedule before performing another external probe, so temporary watchers naturally disappear with the Goal they serve.
-
-## Policy defaults
-
-Allowed without extra approval:
-
-- Read Gmail, Calendar, and Tasks.
-- Create a Google Task / reminder.
-- Create a Gmail draft.
-- Create a personal calendar event without attendees.
-
-Requires human approval:
-
-- Send email.
-- Trash email.
-- Cancel calendar event.
-- Reschedule calendar event.
-- Delete task.
-- Scheduled routine writes beyond explicitly allowed draft/reminder behavior.
-
-## Assistant Inbox
-
-Assistant Inbox is the user-facing result surface for meaningful routine outputs, approval/authentication needs, and intent execution records. A successful scheduled probe with no external change should remain silent rather than generating a daily "completed" notification. ChatGPT can read meaningful items and then present the result conversationally, for example: "今天助理整理了什么？"
-
-## Current limitation
-
-The runtime does not embed a full NLP model. ChatGPT Actions should provide structure when precision matters. The local runtime includes conservative intent inference only for routine creation, reminders, and immediate mail-summary collection.
-
-`browser_watch` is a fallback observation source for services without a usable API or webhook; it depends on a live authenticated browser session and caller-supplied selectors/terms when the page contains unrelated or volatile content. Browser refresh can reduce inactivity-related logout but cannot override a provider's absolute session lifetime, security checks, or MFA policy. Provider-native APIs/events should replace browser probes when they are available and more reliable.

package/docs/operations/gmail-assistant-routines.md

@@ -1,186 +0,0 @@
-# Durable Gmail Assistant Routines
-
-Gmail Assistant Routines use the existing Repository Schedule Engine and durable Execution Jobs. They do not introduce a second cron service.
-
-## Execution flow
-
-1. Creating a confirmed Assistant Routine persists the Routine and creates one Repository Schedule.
-2. The Schedule stores an IANA timezone, a five-field local cron expression, and a bounded catch-up window.
-3. A due occurrence creates one `assistant_routine_execute` Runtime Job with an exclusive Routine resource claim.
-4. The Runtime Job reads Gmail incrementally, hydrates bounded message bodies, advances the per-Routine cursor, analyzes the bounded message set, creates structured action proposals, and writes a final Assistant Inbox report.
-5. Proposals either remain pending for explicit approval or match a previously authorized Standing Grant.
-6. Every approved or Standing-Grant action runs as a separate durable plugin Job. Schedule execution never becomes remote-write authorization.
-7. Sending mail and moving mail to Trash retain their existing strong-confirmation requirements and are never Standing-Grant eligible.
-
-## Google OAuth setup
-
-Create a Google OAuth client with this loopback redirect URI:
-
-```text
-http://127.0.0.1:8766/oauth/google/callback
-```
-
-Expose the client configuration only through the managed secret environment:
-
-- `FORGE_GOOGLE_CLIENT_ID`
-- `FORGE_GOOGLE_CLIENT_SECRET`
-
-The `FORGE_GOOGLE_WORKSPACE_CLIENT_ID` and `FORGE_GOOGLE_WORKSPACE_CLIENT_SECRET` aliases are also supported.
-
-Call `workspace_auth_login_prepare` for `gmail` or `google-workspace`, then open the returned authorization URL. The request uses OAuth Authorization Code flow with PKCE, a random one-time state, a ten-minute expiry, and a loopback-only callback. Redirect URIs outside `127.0.0.1` or `localhost`, unexpected callback paths, and scopes outside the Gmail/Calendar/Tasks allowlist are rejected.
-
-The callback exchanges the authorization code and stores only the refresh token in macOS Keychain. Access and refresh tokens are never returned through MCP, written to repository files, or written to normal Controller runtime state. The transient PKCE verifier is stored under Controller Home with restrictive permissions and is redacted after the callback is consumed.
-
-The current secure persistence backend is macOS Keychain. Non-macOS hosts must provide a supported credential-store adapter or use managed environment credentials.
-
-## Credential refresh and readiness
-
-A configured access token is not considered provider-verified until a real Google API request succeeds. Before that first successful probe, health reports `live_token_unverified`.
-
-After OAuth setup, Controller restarts can reload the refresh token from Keychain. When no valid cached access token exists, or Gmail returns HTTP 401/403, the provider performs one refresh-token exchange and at most one request retry. A failed refresh is classified as `PLUGIN_AUTH_FAILED`; the Routine Run becomes `auth_required` and Assistant Inbox requests reauthorization.
-
-Managed environment credentials remain compatible:
-
-- `FORGE_GMAIL_ACCESS_TOKEN`
-- `FORGE_GMAIL_REFRESH_TOKEN`
-- `FORGE_GMAIL_CLIENT_ID`
-- `FORGE_GMAIL_CLIENT_SECRET`
-- `FORGE_GOOGLE_WORKSPACE_ACCESS_TOKEN`
-- `FORGE_GOOGLE_WORKSPACE_REFRESH_TOKEN`
-- `FORGE_GOOGLE_WORKSPACE_CLIENT_ID`
-- `FORGE_GOOGLE_WORKSPACE_CLIENT_SECRET`
-
-## Scheduling semantics
-
-Routine schedule text is normalized when the Routine is created. The first implementation recognizes daily and weekday expressions with an optional `HH:mm` or Chinese `点/时` form. Examples:
-
-- `每天 09:00`
-- `每周一 08:30`
-- `Monday 07:00`
-
-The normalized Schedule preserves the IANA timezone, so daylight-saving transitions remain aligned to local wall-clock time. Missed runs catch up at most once inside the configured window because the occurrence key is derived from the local scheduled minute rather than the actual wake-up minute.
-
-## Gmail History cursor
-
-Each Routine stores an independent cursor under `.forge/assistant/gmail-cursors.json`:
-
-- last successful collection time
-- bounded processed-message ID set
-- Gmail `historyId`
-- a bounded History or query continuation token while a backlog is still being drained
-
-After the initial query, Gmail History is the primary incremental source. An expired History ID falls back to a five-minute-overlap Gmail query. Collection reads at most five pages, 100 IDs, and 50 full messages per run. If the page or hydration limit is reached, the history cursor does not advance; a continuation token or the original window is retained so the next run drains the remaining messages without loss.
-
-## Optional model analysis
-
-The model layer is optional. When it is disabled, unavailable, times out, or returns malformed output, the Routine completes with the deterministic rules engine rather than failing.
-
-Configure an OpenAI-compatible endpoint with:
-
-- `FORGE_ASSISTANT_MODEL_PROVIDER=openai-compatible`
-- `FORGE_ASSISTANT_MODEL_ENDPOINT`
-- `FORGE_ASSISTANT_MODEL`
-- `FORGE_ASSISTANT_MODEL_API_KEY`
-
-For the exact official hosts, provider-specific keys are also supported:
-
-- `api.openai.com` may use `OPENAI_API_KEY`
-- `api.deepseek.com` may use `FORGE_DEEPSEEK_API_KEY` or `DEEPSEEK_API_KEY`
-
-A custom endpoint never receives `OPENAI_API_KEY` or a DeepSeek key. It must use the dedicated `FORGE_ASSISTANT_MODEL_API_KEY`. Endpoints must use HTTPS, except loopback HTTP used for a local model.
-
-Optional budgets:
-
-- `FORGE_ASSISTANT_MODEL_TIMEOUT_MS`
-- `FORGE_ASSISTANT_MODEL_MAX_MESSAGES`
-- `FORGE_ASSISTANT_MODEL_MAX_INPUT_CHARS`
-- `FORGE_ASSISTANT_MODEL_MAX_OUTPUT_TOKENS`
-
-The provider requests strict structured JSON, validates the result locally, and maps only these proposal types:
-
-- Gmail draft creation
-- Google Task creation
-- Gmail archive
-- Gmail mark read or unread
-
-Email contents are untrusted input. Instructions in an email, quoted thread, signature, link, or attachment description cannot expand the action allowlist or request tools, credentials, files, commands, or additional permissions. Security, authentication, billing, incident, production, quota, and repository-permission messages are protected from model-generated archive actions.
-
-The deterministic fallback also uses Gmail's `CATEGORY_PROMOTIONS` label as a high-confidence archive signal (`0.98`) for non-protected messages. Marketing/newsletter keyword matches remain a lower-confidence fallback (`0.7`). The protected-message veto wins over both signals, so a security, authentication, billing, production, incident, quota, or permission-related message is never proposed for automatic archive merely because Gmail classified it as Promotions.
-
-Use `assistant_model_readiness` or `GET /api/assistant/model` to inspect the redacted configuration and budgets. Model credentials and raw secrets are never returned.
-
-## Action proposals and approval
-
-Routine analysis persists structured proposals under `.forge/assistant/action-proposals.json`. Each proposal records:
-
-- Routine and Run identity
-- target plugin/action and bounded arguments
-- supporting Gmail message IDs
-- sender/subject context and protected-message status
-- reason, confidence, risk, expiry, and execution status
-- the separate Execution Job created after approval
-
-Use `assistant_action_proposals` to list or inspect proposals. Use `assistant_action_proposal_resolve` with `decision=approve` or `decision=reject`. MCP approval requires `confirm_authorization=true`; strong-confirmation actions also require the action's exact confirmation text. Local Controller exposes equivalent authenticated proposal endpoints.
-
-Approval is idempotent. Repeating approval returns the same Execution Job rather than creating another remote write. Proposal audit records preserve whether approval came from MCP, Local UI, or a Standing Grant.
-
-## Standing Grants
-
-A Standing Grant is an explicit, expiring pre-authorization for one hardcoded low-risk action. It is not a general plugin permission.
-
-Eligible actions are limited to:
-
-- `gmail.create_draft`
-- `gmail.archive_message`
-- `gmail.mark_message_read`
-- `gmail.mark_message_unread`
-- `google_tasks.create_task`
-
-A grant must include at least one constraint:
-
-- Routine ID allowlist
-- sender/domain allowlist
-- required subject fragment
-
-It also declares minimum proposal confidence, maximum executions per Routine Run, and expiry. Automatic draft grants additionally require a sender allowlist. Security-protected messages cannot be auto-archived.
-
-Create a grant through `assistant_standing_grant_create` or `POST /api/assistant/standing-grants` with explicit authorization. List it through `assistant_standing_grants`; revoke it through `assistant_standing_grant_revoke` or the Local Controller revoke endpoint.
-
-Example: automatically archive at most one high-confidence newsletter from a trusted sender per run:
-
-```json
-{
-  "plugin_id": "gmail",
-  "action_id": "archive_message",
-  "sender_allowlist": ["news@example.com"],
-  "subject_contains": ["newsletter"],
-  "min_confidence": 0.9,
-  "max_per_run": 1,
-  "expires_in_days": 30,
-  "confirm_authorization": true
-}
-```
-
-Standing-Grant executions use a dedicated `standing-grant` origin and a defense-in-depth plugin allowlist. Modifying the stored grant cannot enable send, Trash, permanent deletion, calendar cancellation/rescheduling, or task deletion. Multiple matching grants cannot submit the same proposal twice, and retries preserve each grant's per-run budget.
-
-## Safety boundary
-
-Scheduled Routines may:
-
-- list and read Gmail messages
-- classify and summarize collected mail
-- create bounded draft, task, archive, and read/unread proposals
-- execute an eligible proposal only when a matching active Standing Grant already exists
-- write Assistant Inbox reports
-
-Scheduled Routines may not:
-
-- send mail
-- move mail to Trash
-- permanently delete mail
-- cancel or reschedule meetings
-- delete tasks
-- execute instructions embedded in mail
-- open arbitrary attachments or links
-
-A proposal is evidence for a later authorized action, not implicit authorization. A Standing Grant authorizes only its exact action and constraints. The Schedule origin never becomes authorization for a remote write.