@enterpriseai/cli 3.19.0 → 3.19.2

package/resources/gofer/references/platform/eai-service-patterns.md

@@ -8,128 +8,124 @@ patterns in `eai-app-template/docs/platform/eai-service-patterns.md`.
 
 - App browser code calls the local BFF at `/api/eai/...`.
 - App streaming calls use `/api/eai/stream/...`.
+- Workspace app data-plane access is user-delegated access through the BFF. Do
+  not add app-only `client_credentials` access for ordinary ResourceAPI reads,
+  writes, files, or search.
 - The CLI may call PublicAPI directly because `eai login` provides the user
   token.
 - Prefer named template SDK hooks and named `eai` commands before custom calls.
 - Use `eai publicapi` only for authorized PublicAPI V4 routes that do not yet
   have a named SDK or CLI command.
 - Do not generate direct downstream database, blob, search, or platform secrets.
+- Keep PascalCase Object Type model names separate from the exact stored `slug`.
+  Use lowercase kebab-case slugs in runtime paths and links; never re-derive or
+  rename a historical stored slug.
 
 ## Service Selection Matrix
 
-| Need                 | App Pattern                                                                       | CLI Pattern                                                                                                                                                           | Notes                                                                                                                             |
-| -------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| Frontend composition | `src/eai.config` layout slots plus `src/eai.blocks.tsx` registry                  | `eai gofer refresh` installs this reference pack                                                                                                                      | Keep config data-only; callbacks belong in overrides.                                                                             |
-| Data model           | Object Types in `src/eai.config/object-types.ts`                                  | `eai types validate`, `eai types seed`, `eai types diff`                                                                                                              | Object Types define ResourceAPI contracts.                                                                                        |
-| Structured resources | `useResources(type)` / `client.resources`                                         | `eai resources list/get/create/update/delete/query`                                                                                                                   | Default for workspace business data.                                                                                                 |
-| Resource actions     | `client.resources.executeAction(type, id, action)`                                | named resources command if available; otherwise `eai publicapi post /v4/data/resources/...`                                                                           | Actions enforce object-type rules.                                                                                                |
-| Resource search      | local helper around `/v4/data/resources/{tenantId}/search` if SDK support is absent | `eai resources storage doctor --format json`, then `eai resources search "query" --fulltext`; use `--hybrid` or `--vector` only when doctor reports those modes ready | The stable route parameter is `{tenantId}`; its value is the EAI workspace ID. V4 passive ResourceAPI search is a projection over canonical data. Fulltext can be usable before semantic search modes are ready. |
-| Resource files       | local helper around resource file routes                                          | `eai resources file upload/get/delete`                                                                                                                                | Use when the file is attached to a typed ResourceAPI object property.                                                             |
-| Documents | One `useDocuments().upload(file, context)` OR `classify([file], context)` | One `eai docs upload` OR `eai docs classify`, with authorized context | Queued ResourceAPI upload; follow the document lifecycle rules below. |
-| Chat                 | `useChat(workflowId, stage).send/stream`                                          | `eai chat send`, `eai chat stream`                                                                                                                                    | Use v4 chat shape with `message`, `conversation_id`, and `params`.                                                                |
-| Advanced PublicAPI   | BFF/server helper                                                                 | `eai publicapi <method> /v4/...`                                                                                                                                      | Use only when named SDK/CLI support is missing.                                                                                   |
+| Need                  | App Pattern                                                                                                           | CLI Pattern                                                                                                                                                           | Notes                                                                                                                                                                                                                      |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Frontend composition  | `src/eai.config` layout slots plus `src/eai.blocks.tsx` registry                                                      | `eai gofer refresh` installs this reference pack                                                                                                                      | Keep config data-only; callbacks belong in overrides.                                                                                                                                                                      |
+| Data model            | Object Types in `src/eai.config/object-types.ts`                                                                      | `eai app provision`, `eai types validate --tenant-key <key> --tenant-id <tenant-id>`, `eai types seed`, `eai types diff`                                              | Object Types define ResourceAPI contracts and must use app-owned storage bindings.                                                                                                                                         |
+| Structured resources  | `useResources(type)` / `client.resources`                                                                             | `eai resources list/get/create/update/delete/query`                                                                                                                   | Default for workspace business data. For workspace-scoped calls, treat the workspace ID in the path as canonical and have the app BFF forward both `tenant` and `X-Tenant-Id` headers with that ID server-authoritatively. |
+| Resource actions      | `client.resources.executeAction(type, id, action)`                                                                    | named resources command if available; otherwise `eai publicapi post /v4/data/resources/...`                                                                           | Actions enforce object-type rules.                                                                                                                                                                                         |
+| Resource search       | local helper around `/v4/data/resources/{tenant}/search` if SDK support is absent                                     | `eai resources storage doctor --format json`, then `eai resources search "query" --fulltext`; use `--hybrid` or `--vector` only when doctor reports those modes ready | V4 passive ResourceAPI search is a projection over canonical data. Fulltext can be usable before semantic search modes are ready.                                                                                          |
+| Resource files        | local helper around resource file routes                                                                              | `eai resources file upload/get/delete`                                                                                                                                | Use when the file is attached to a typed ResourceAPI object property.                                                                                                                                                      |
+| Documents             | `useDocuments().upload(file, context)`, `useDocuments().classify([file], context)`, or `useDocuments().ragIndex(...)` | `eai docs upload`, `eai docs classify`, or `eai docs index` with authorised context                                                                                   | Use the queued ResourceAPI document lifecycle below; index only a persisted document where the configured lifecycle supports it.                                                                                           |
+| Content understanding | Document and media extraction behind the app BFF                                                                      | `eai docs classify` with authorised context; use other commands only when advertised                                                                                  | Classification needs a configured app/workflow and persisted result readback before it is considered complete.                                                                                                             |
+| Chat                  | `useChat(workflowId, stage).send/stream`                                                                              | `eai chat send`, `eai chat stream`                                                                                                                                    | Use v4 chat shape with `message`, `conversation_id`, and `params`.                                                                                                                                                         |
+| AI services           | Template AI hooks and workflow-backed assistant steps                                                                 | `eai agent guide --format json`, advertised `eai ai` or workflow commands                                                                                             | Prefer platform AI services for app behavior. Avoid direct provider keys in app code unless EAI documents that integration.                                                                                                |
+| Workflows             | Workflow-backed tasks that can continue across user sessions                                                          | `eai workflow readiness --format json` and advertised workflow commands                                                                                               | Use for multi-step business processes, approvals, background work, and auditable state changes.                                                                                                                            |
+| Goals and targets     | Goal/target records tied to resources and workflow outcomes                                                           | `eai workflow readiness --format json`, `eai resources schema --format json`, and advertised goal/target commands                                                     | Use when the app must track business outcomes, service levels, operating targets, or completion evidence.                                                                                                                  |
+| Advanced PublicAPI    | BFF/server helper                                                                                                     | `eai publicapi <method> /v4/...`                                                                                                                                      | Use only when named SDK/CLI support is missing.                                                                                                                                                                            |
+
+## Workspace-Scoped Resource Diagnostics
+
+- For `/v4/data/resources/{tenantId}/...` requests, compare the same call in
+  four header modes before concluding the workspace is unprovisioned: workspace
+  ID only, `tenant` only, `X-Tenant-Id` only, and both headers.
+- If the same workspace-scoped endpoint flips between `200` and `503` based on
+  headers, suspect a workspace-context contract mismatch before an install or
+  schema failure.
+- Inspect the app BFF or proxy code before escalating to a platform-only fault.
+  The default app-template proxy should forward both workspace-context headers
+  server-authoritatively for workspace-scoped PublicAPI calls.
+- Treat `/v4/platform/tenants/{tenantId}/resource-metadata` and its
+  `publishedObjectTypes` as operational state, not descriptive metadata only.
+  Empty or stale published types can block `/storage` readiness even when the
+  workspace and app exist.
+- Use `eai resources storage doctor --tenant-id <tenant-id> --format json`
+  alongside direct `/storage` checks so install, schema, and projection issues
+  are evaluated from the workspace's public contract.
+
+If work must continue after the user leaves the page, have the signed-in user
+request a platform workflow/job and pass workspace, app, user, and purpose
+context into that workflow. Do not give the workspace app a broad service
+identity for normal data-plane access.
 
 ## Document Lifecycle Rules
 
-The #3453 standalone lifecycle is a candidate, not deployed capability or live
-acceptance evidence. Before generating or enabling an upload, verify the
-installed CLI/SDK supports the context contract and the target runtime supports
-the configured lifecycle. Provision the business document/analysis schemas and
-Admin Portal lifecycle binding first. Storage readiness and classifier
-readiness are separate checks; a published classifier alone is not enough.
-
-- Use one `POST /v4/data/documents/upload` for durable upload and queued
-  classification, with `storage_target=resourceapi`. Browser callers use the
-  local BFF `/api/eai/v4/data/documents/upload`; tokens stay server-side.
-- For standalone documents, send both `verticalKey` and `workflowKey`. PublicAPI
-  validates the authorised app/workflow and resolves optional
-  `config.documentLifecycle` on the existing classifier-target
-  `vertical-product-config` binding, never from the upload body.
-- Allowed binding values are `planning-assist-v1`, `planning-assess-v1`, and
-  `business-document-v1`. Omission preserves existing behaviour and does not
-  erase a saved selection on reassociation. Unsupported values fail validation.
-  Missing planning fields do not imply business mode.
-- Preserve working DAISY/Assess requests, planning/case relationships, rules,
-  stored records and in-flight jobs. Retain real authorised
-  `planning_application_id`, `business_request_id` and applicable
-  `assess_case_id` context (SDK: `planningApplicationId`, `businessRequestId`,
-  `assessCaseId`). Never fabricate a planning application, business request,
-  case or form submission for a standalone document. Optional real parents
-  must be supported by the selected lifecycle and authorised.
-- Call `classify([file], context)` for `processing_mode=classification`, OR
-  `upload(file, context)` for full requested processing. Do not upload and then
-  classify the same bytes again. The SDK supplies `storage_target=resourceapi`.
-  Do not generate context-free legacy file classification or a fallback to it.
-- Do not send lifecycle mappings, target collections, permissions, provider
-  credentials or worker pins from the client. Missing schema, storage,
-  service, app/workflow or classifier readiness must fail before upload-side
-  writes, not fall back to legacy storage or an unscoped classifier.
-- Retain the returned job/document IDs. Poll
-  `GET /v4/data/documents/jobs/{job_id}` with authorised context and read back
-  saved requested stages and provenance. Acknowledgement and provider success
-  are not completed classification, extraction, rule validation or persistence.
-  A polling timeout is incomplete; never re-upload automatically.
-- Indexing is an optional derived stage only where supported and requested.
-  Use authorised lifecycle file retrieval and cleanup. Invalidate stale work
-  and clean only owned outputs according to retention, never shared parents.
-- Direct `POST /v4/data/documents/classify-by-url` is analysis, not a durable
-  queued upload/save/readback/cleanup replacement. New workflow-selected URL
-  callers also supply the app/workflow pair. Preserve established unscoped
-  DAISY/Assess classifier behaviour without making it a new business-app default.
-
-Candidate example after provisioning and version checks, submitted once:
-
-```tsx
-const { classify } = useDocuments(tenantId);
-const response = await classify([file], {
-  verticalKey: appKey,
-  workflowKey,
-});
-if (!response.ok) throw new Error("Document submission failed.");
-const accepted = await response.json();
-```
-
-Retain the returned IDs and implement bounded status polling plus saved-result
-readback before reporting success. The equivalent CLI submission is:
-
-```bash
-eai docs classify ./document.pdf --tenant-id <tenant-id> \
-  --storage-target resourceapi --vertical-key <app-key> --workflow-key <workflow-key>
-```
-
-An authorised administrator selects the binding with
-`eai classifier target <classifier-key> --app <app-key> --workflow <workflow-key>
---document-lifecycle business-document-v1` after schema/storage and published
-classifier readiness checks. Verify this syntax with the installed command's
-`--help`. `--document-lifecycle` is a target-administration option, not an upload
-option.
-
-Scope is document-use migration, not all v3 retirement. Existing-record
-read/download/delete/status, old queued callbacks, reference files and real
-form attachments remain compatibility obligations. Replacement, client and
-tenant-setup proof must precede enforcement against approved new legacy
-admissions. Track package/plugin/docs publication and installed adoption
-separately from local source or generator checks; do not claim live acceptance.
-
+- Durable uploads and queued classification use
+  `POST /v4/data/documents/upload`. Browser callers use the app BFF at
+  `/api/eai/v4/data/documents/upload`.
+- Use `storage_target=resourceapi`. For a standalone business document, provide
+  both `verticalKey` and `workflowKey`; PublicAPI authorises that scope and
+  resolves the published classifier binding. Do not send a classifier, storage
+  mapping, provider credential, or lifecycle mapping from the client.
+- Use `classify([file], context)` for classification-only processing, or
+  `upload(file, context)` for the full requested lifecycle. Do not fall back to
+  the retired context-free `/v4/data/documents/classify` route.
+- Retain the accepted document and job identifiers. Poll the authorised job
+  endpoint, read back the persisted result, and clean only the outputs the
+  caller created according to the workspace retention policy.
+- `POST /v4/data/documents/classify-by-url` is direct analysis, not a durable
+  upload, stored-result, or cleanup replacement. Existing DAISY and Assess
+  planning/case context remains a compatibility obligation; do not fabricate it
+  for a standalone business document.
 
 ## Storage Backend Rules
 
-Keep Object Type identifiers in their correct layer. Configuration/model
-`name` is PascalCase; the exact stored `slug` is the lowercase
-kebab-case identifier used by relationship targets, runtime `target_type`,
-resource commands, paths, and governed v4 fields. Resolve same-manifest model
-name shorthand through the declared slug before publication. Never normalize
-or rename a historical stored slug.
-
-- `postgresql`: canonical structured resource storage.
-- `documentdb`: document-model persistence when the data genuinely needs it.
-- `blob`: large files or file-like resources behind API-mediated access.
+Workspace app Object Types must use app-owned storage bindings. For PostgreSQL
+types, use the `tenant-postgres` alias and table names that include the
+tenant/app prefix validated by
+`eai types validate --tenant-key <key> --tenant-id <tenant-id>`. Do not invent
+storage aliases or generic table names; derive them from `eai app provision`,
+`.eai/storage-bindings.json`, and the local Object Type helper.
+
+- `postgresql`: default for relational, transactional, reporting, workflow
+  state, audit, and structured workspace business data.
+- `documentdb`: document-model persistence for flexible JSON documents, nested
+  records, high-change schemas, and user-authored document state.
+- `blob`: large files, binary content, exports, and file-like resources behind
+  API-mediated access.
 - `search`: derived full-text/vector/hybrid projection, not the sole system of
   record for runtime writes. On the v4 passive ResourceAPI interface, treat
   full-text readiness separately from hybrid/vector readiness; semantic modes
   require `eai resources storage doctor` to report `capabilities.search.hybrid`
-  or `capabilities.search.vector`. Do not apply this fallback rule to legacy
-  v1/v3 or active ResourceAPI behavior.
+  or `capabilities.search.vector`. Apply this fallback only to the published
+  passive ResourceAPI search contract.
+- `content understanding`: use the EAI document and content services before
+  custom extraction code when the app must classify, extract, summarize, or
+  prepare evidence from documents or media.
+- `workflows`: use the EAI workflow layer for approvals, long-running work,
+  service goals, operating targets, and cross-user process state.
+- `AI services`: use platform AI hooks and workflow-backed agents first. Do not
+  add direct provider keys, ad hoc LLM clients, or non-EAI AI services unless
+  the platform lacks the capability and the exception is approved.
+
+## Business Decision Rules
+
+When Gofer plans an EAI app, it should make the normal platform choice on behalf
+of the business user.
+
+1. Use the simplest EAI Platform service that satisfies the requirement.
+2. Record the choice and reason in `service-fit-matrix.md`.
+3. Ask the user only when the choice affects cost, security, compliance,
+   deployment, data residency, external systems, or material business scope.
+4. If a capability appears missing, run live CLI discovery before recommending a
+   non-EAI service.
+5. If EAI does not expose the capability, use Azure second.
+6. Use any other platform only with explicit exception evidence.
 
 Document RAG indexing is a documents service pattern (`eai docs index` or
 `useDocuments().ragIndex(...)`), not a reason to create a search-only Object
@@ -137,8 +133,9 @@ Type.
 
 Do not create standalone PublicAPI v4 blob-upload flows. If a user asks to
 upload a file, first decide whether the file is a document workflow input or a
-ResourceAPI file property. Ask which workspace, workflow/stage, document purpose,
-Object Type, resource ID, and file property are involved before writing code.
+ResourceAPI file property. Ask which workspace, workflow/stage, document
+purpose, Object Type, resource ID, and file property are involved before writing
+code.
 
 ## Config-Driven UI Rules
 

package/resources/gofer/references/platform/eai.md

@@ -4,12 +4,25 @@ Use this fallback when external CLI documentation is unavailable.
 
 ## Version Pinning Rule
 
+For authentication, use `.specify/references/platform/eai-auth-access.md`.
+Confirm workspace-only access (the default) or explicitly approved wider app
+access. Confirm client SSO separately; sign-in never replaces authorization.
+
 - Detect the installed CLI version.
 - Record the `major.minor` version in generated plan and task artifacts.
 - Avoid pinning implementation guidance to patch-specific behavior.
 
 ## Command Guidance Contract
 
+- Do not invent, guess, or complete EAI CLI commands from memory.
+- Before suggesting or running an `eai ...` command, verify the exact command
+  and flags from the installed CLI.
+- Start with `eai --describe`.
+- For a specific command, run `eai <command> --help` or the CLI-described
+  equivalent before using subcommands, flags, or examples.
+- If the command is not listed or help fails, do not run it. Say the installed
+  EAI CLI does not expose that command, then choose a safe listed command or ask
+  the user to update EAI CLI.
 - Use live CLI discovery before assuming syntax:
   - `eai update --check`
   - `eai --describe`
@@ -22,6 +35,9 @@ Use this fallback when external CLI documentation is unavailable.
   - `eai workflow readiness --format json` when advertised
   - `eai provision entra` when identity callback or Entra registration setup is
     in scope
+- Before architecture or storage decisions, read
+  `.specify/references/platform/eai-service-patterns.md` and record the service
+  choice in `.specify/specs/{feature}/service-fit-matrix.md`.
 - When any `eai` command fails, run
   `eai errors explain <code-or-reason> --format json` when advertised and use
   its public-safe reasons and next commands before guessing remediation.
@@ -49,9 +65,29 @@ Unless the live CLI advertises a different dependency order:
 4. Confirm or create/select the app
 5. Provision app resources
 6. Run object-type validation and publish
-7. Verify schema, storage, and workflow readiness
+7. Verify schema, storage, workflow, goals, targets, and platform AI readiness
 8. Start preview or dev runtime
 
+## Platform Service Selection
+
+For EAI app delivery, Gofer should choose the normal platform service without
+making the business user learn the platform internals.
+
+- Use PostgreSQL for relational, transactional, reporting, workflow state, and
+  structured workspace business data.
+- Use DocumentDB for flexible JSON documents, nested records, and high-change
+  document models.
+- Use Blob Storage for files, media, exports, and large binary content.
+- Use AI Search as a derived search projection over a source of record.
+- Use content understanding and document services for extraction,
+  classification, summarization, and Retrieval-Augmented Generation.
+- Use workflows, goals, and targets for business processes, approvals,
+  service-level tracking, and operating outcomes.
+- Use platform AI services before direct provider SDKs or provider keys.
+
+Ask for user input only when the choice changes cost, security, compliance,
+deployment, data residency, external systems, or material business scope.
+
 Do not treat provisioning, object-type publish, schema/storage health, workflow
 readiness, and preview as interchangeable states.
 
@@ -67,8 +103,8 @@ For workspace member or admin changes, use EAI CLI membership commands first. If
 `eai user invite` fails with `EXTERNAL_SERVICE_ERROR`, a 5xx status, or the
 `user_invite_external_service_existing_member` reason, check whether the person
 already exists with
-`eai user list --workspace <workspace-id> --search <email> --format json`. If a direct
-member exists and the user approves the role change, use
+`eai user list --workspace <workspace-id> --search <email> --format json`. If a
+direct member exists and the user approves the role change, use
 `eai user role set --workspace <workspace-id> --member-id <member-id> --role tenant-admin --format json`,
 verify the read-back, then tell the affected app user to sign out and sign back
 in because Auth.js session or JWT role data may be cached. Do not use direct
@@ -77,10 +113,10 @@ operator-only block.
 
 If a browser sign-in flow reports `AADSTS50011` or a Microsoft Entra redirect
 URI mismatch, do not start with manual Azure Portal edits. Confirm the EAI login
-and workspace, confirm the callback URI from the failing authorize request in the
-active session, then run the advertised
+and identity-provider tenant, confirm the callback URI from the failing
+authorize request in the active session, then run the advertised
 `eai provision entra --force --redirect-uri <confirmed-callback-uri>` path and
 retry sign-in. Record only a redacted callback route in Gofer artifacts. Use
-`--debug` only with explicit user approval, and redact private hostnames, private
-workspace/platform tenant IDs, Entra/CIAM authority tenant IDs, client IDs,
-tokens, and raw debug output before writing artifacts.
+`--debug` only with explicit user approval, and redact private hostnames,
+private workspace/platform tenant IDs, Entra/CIAM authority tenant IDs, client
+IDs, tokens, and raw debug output before writing artifacts.

package/resources/gofer/references/platform/vertical-template.md

@@ -1,7 +1,7 @@
 # Vertical Template Reference
 
-Use `https://github.com/eai-support/eai-app-template` as the canonical public app
-template for EnterpriseAI app-delivery work.
+Use `https://github.com/eai-support/eai-app-template` as the canonical public
+app template for EnterpriseAI app-delivery work.
 
 This file is the preferred alias for the legacy `eai-app-template.md` fallback
 reference. Both names are kept so older EnterpriseAI consumers and newer public
@@ -23,10 +23,11 @@ Gofer terminology resolve to the same guidance.
 
 1. Browser code calls the local app BFF at `/api/eai/...`.
 2. Browser streaming uses `/api/eai/stream/...`.
-3. The BFF or server helpers attach auth, workspace, and correlation headers.
+3. The BFF or server helpers attach auth, tenant, and correlation headers.
 4. The frontend never receives direct downstream database, blob, search, or
    PublicAPI credentials.
-5. Use PublicAPI V4 surfaces for direct platform calls.
+5. Use the published PublicAPI route family through the template SDK, named
+   `eai` commands, or an approved server-side helper.
 
 ## Implementation Contract
 
@@ -39,11 +40,11 @@ Gofer terminology resolve to the same guidance.
 - Use the CLI for setup and verification:
   - `eai login`
   - `eai workspace select <workspace-slug>`
-  - `eai types validate`
-  - `eai types seed --tenant-key <key> --tenant-id <workspace-id>`
-  - `eai types diff --tenant-key <key> --tenant-id <workspace-id>`
-  - `eai resources schema --tenant-id <workspace-id>`
-  - `eai verify calls --tenant-id <workspace-id> --resource-type <type>`
+  - `eai types validate --tenant-key <key> --tenant-id <tenant-id>`
+  - `eai types seed --tenant-key <key> --tenant-id <tenant-id>`
+  - `eai types diff --tenant-key <key> --tenant-id <tenant-id>`
+  - `eai resources schema --tenant-id <tenant-id>`
+  - `eai verify calls --tenant-id <tenant-id> --resource-type <type>`
 
 Do not describe retired templates as canonical scaffolds. The surviving public
 scaffold is the EAI App Template.

package/resources/gofer/references/priority-outcome-protection.md

@@ -0,0 +1,152 @@
+# Keep The Agreed Outcome
+
+Gofer must stay on the user's priority, not merely complete available tasks.
+These rules extend the existing pipeline, not replace it.
+
+## Before Work And After Resume
+
+Record material changes to the goal, priority, scope or permission in the
+private feature decisions.md before acting. Resolve what a short instruction
+such as "do it" refers to. Do not copy secrets or every routine chat message.
+Update spec.md, plan.md, tasks.md and traceability when affected. Do not invent
+approval where approval is required.
+
+## Goal-Led Autonomy
+
+The stated goal authorizes Gofer to make ordinary delivery decisions. Gofer
+must choose the next safe task, design, investigation, repair, test, and
+reversible repository change without asking the user to manage the process.
+Record each material Gofer decision with its identifier, chosen path, reason,
+scope, and business effect. Tell the user what changed in concise progress
+updates. A recorded Gofer decision is sufficient for independent work that the
+priority plan proves is safe.
+
+Ask the user only when Gofer cannot safely own the decision:
+
+- The goal, success measure, or target environment is unclear or changes.
+- The action causes irreversible loss, external spending, legal commitment,
+  production/public exposure, or a security/access change.
+- Required authority, credentials, an account action, or a host permission is
+  missing.
+- A safe in-scope diagnosis and repair cannot remove a blocker within the
+  retry limit.
+- The proposed action conflicts with an explicit user constraint.
+
+Do not ask for ordinary technology choices, task order, safe repair choices,
+or evidence collection. Do not present several technical options when one
+safe option best advances the goal. Use the chosen option, record why, and
+continue.
+
+Create priority-plan.json from the template by the tasks stage. Include every
+task ID, its prerequisites and an explicit allowedEditScope. Paths are relative
+to the repo: exact files or directories ending in `/`, not wildcards. Include
+feature evidence paths where the task writes them. Empty scope means read-only.
+Record `lastInstruction` in decisions.md. Keep this plan under the existing
+delivery checkpoint so an unnoticed direction change fails the freshness check.
+
+Before a task, run:
+
+```sh
+node .specify/scripts/node/gofer-priority-check.mjs --feature-dir <feature-dir> --task T001
+```
+
+Supply `--workspace <repo-root>` and `--changed-file <repo-relative-path>` for
+every intended edit and again for the actual diff. The helper is read-only. It
+does not intercept host tools; the agent must inspect the full diff, including
+untracked files and other repos. The checker resolves existing parents of
+proposed files and rejects symlinks that escape the approved scope. Recheck
+immediately before an edit; the host still controls the actual write. It rejects
+non-regular files and oversized records (4 MiB documents, 64 MiB per evidence
+file, 128 MiB total unique evidence per review). Aliases reuse the same raw-file
+hash. Keep focused evidence in the feature; do not weaken required checks to
+reduce the record size. Task graphs are bounded at 20,000 tasks and 100,000
+dependencies. Split larger work into reviewed features.
+
+Follow `nextTask`. It resolves the first open priority task and its unfinished
+prerequisites. Independent parallel work requires `parallelFor`, a reason and
+a recorded decision ID. The decision can be a Gofer decision when the work is
+within the goal, declared scopes, limits, and safety rules. A blocked priority
+never authorizes unrelated chores. Changing scope requires updating the plan and
+user understanding, not bypassing the check. Preserve all release/security gates
+even for unrelated failures.
+
+On resume, read the saved direction, goal, tasks and evidence before acting.
+Say: "We are proving sign-in works. I will first check the failed login." Do not
+dump internal IDs in routine progress updates.
+
+## Before Asking For Help
+
+Use the existing blocker controller and retry budget. For a technical blocker,
+the `ask` event needs `verification`, a relative path in its private state
+folder. The JSON diagnosis must include:
+
+- `blockerId`, `kind: "diagnosis"`, `checkedAt` (UTC, within 24 hours),
+  `source`.
+- `classification`: product, tooling, credential, environment or self-caused.
+- `command` and `observed`: the safe check actually performed and its result.
+- `evidence` and `sha256`: the private output file and its raw-file SHA-256.
+- `selfCauseChecked: true` and `selfCauseCheck`: verify syntax, route order,
+  environment and existing configuration against current evidence.
+- `authorizedRepairAvailable: false` and `authorityCheck`: explain why the agent
+  cannot safely repair it within the approved scope and existing access.
+- `alternativeCheck` or `noSafeAlternativeReason`. Logs or current help may be
+  enough. Never replay a destructive action merely to reproduce a failure.
+
+If an authorized repair is available, use the existing bounded recovery instead.
+An expired token needs an actual session check, not an invented tenant. Having
+an admin role does not authorize every change. Real business choices use the
+`decision` category and need no fabricated technical failure. Evidence hashes
+protect saved records from change; they do not certify that a claim is true.
+
+## Prove The Current Outcome
+
+Place the first meaningful user/runtime proof immediately after its minimum
+prerequisites. The scope can be local MVP, non-app research or a deployed
+feature. Do not require future authentication, a cloud deployment, or tenant
+setup for work that does not yet need it. Later release checks remain mandatory.
+
+The plan names the outcome, requirements, target environment/revision and
+receipt. Before completion, run the helper with `--finish`. A receipt must
+contain:
+
+- `result: "pass"`, `outcomeId`, `planHash` and `specHash` (SHA-256 of raw
+  files).
+- `target` matching the agreed environment and exact code/document revision.
+- `requirements` and nonempty `checks`, each with `command`, `result: "pass"`,
+  relative `evidence` path and its raw-file `sha256`.
+
+Traceability must name the receipt for each outcome requirement. Verify the
+deployed revision independently before recording it. Rerun affected checks after
+any code, direction or target change; a renamed or copied file is not new proof.
+The helper checks recorded integrity, not the live environment or user consent.
+
+Missing or failed proof means **outcome unverified**, even when other tests
+pass. Keep those test results visible; do not erase them or claim the whole
+feature passed. Existing task evidence checks still apply to every completed
+task.
+
+New loop contracts require this plan at stages 4-6. Earlier stages do not
+require the final result. Legacy contracts retain their checks with an explicit
+coverage limitation until reviewed and migrated. Conversation-only work needs no
+plan.
+
+Final closed-loop validation also uses
+`gofer-closed-loop-audit.mjs --completion`. Without that flag, the audit checks
+plan structure and drift only; it does not prove completion. The explicit
+completion check requires the plan even for an older feature. Migrate it first
+rather than silently accepting missing evidence.
+
+## Release And Recovery
+
+After this version records diagnostic proofs, do not downgrade to an older
+blocker reader. Older readers reject the new proof type. Keep the current record
+readers and completion argument when preparing a corrective release. User-facing
+policy and new defaults can be reverted in that release without deleting
+evidence or resetting retry budgets. Pause blocked work until the compatible fix
+passes its tests. A package downgrade is not a supported recovery.
+
+Merging release preparation updates the GitHub Pages feed. That is already a
+rollout boundary, even before the Marketplace finishes. If a publishing step
+fails, repair that same version's publication. Do not announce a complete
+release until every required channel serves the checked version and helper
+files.