anymorph 0.2.6 → 0.4.0

package/dist/skillpacks/geo/skills/brand-owned-diagnosis/SKILL.md

@@ -32,7 +32,7 @@ Read these references before producing proposals:
 - `references/diagnosis-contract.md` for the exact runtime diagnosis contract and artifact submission shape.
 
 1. Read shared run context and the brand-owned candidate slice.
-2. Use `list_geo_strategy_candidates` before broad SQL.
+2. Use `list_brand_owned_candidates` before broad SQL.
 3. Use `get_geo_intent_diagnostic` for intent-level explanation.
 4. Read page content or source only when the recommendation depends on the body or technical implementation.
 5. Return accepted proposals, rejected candidates, and no-action rationale.

package/dist/skillpacks/geo/skills/brand-owned-diagnosis/references/diagnosis-contract.md

@@ -19,10 +19,10 @@ Do not propose GEO page generation unless the orchestrator explicitly asks you t
 Use the cheapest sufficient evidence.
 
 1. Common run context and candidate rows from the orchestrator.
-2. `list_geo_strategy_candidates` for the first brand-owned candidate slice.
+2. `list_brand_owned_candidates` for the first brand-owned candidate slice.
 3. `get_geo_intent_diagnostic` for one intent before deeper checks.
-4. `get_page_insights`, `get_page_visibility`, or `list_ai_responses` for page/prompt evidence.
-5. `get_page_content` or `get_page_source_code` only when content or technical diagnosis depends on the page body.
+4. `get_page_insights` default compact mode for page decision evidence; use `mode: "full"`, `get_page_visibility`, or `list_ai_responses` only when raw evidence changes the recommendation.
+5. `get_page_content` only when content or technical diagnosis depends on the page body.
 6. `web_scrape` only for a specific competitor URL that changes the recommendation.
 
 Do not scrape broadly.
@@ -49,14 +49,13 @@ Use `authority_gap` only with external citation evidence or repeated competitor
 
 Allowed families:
 
-- `refresh_existing_page`
+- `update_existing_page`
 - `retarget_existing_page`
-- `improve_entity_clarity`
-- `add_proof`
-- `add_comparison_coverage`
-- `fix_technical_issue`
+- `merge_or_redirect_page`
 - `no_action`
 
+Keep specific fixes such as proof, entity clarity, comparison coverage, and technical repairs in `rootCauses` and `operations`, not as separate action families.
+
 ## Output
 
 Produce one `brand_owned` diagnosis object in this shape.
@@ -78,7 +77,7 @@ Use this shape:
       "rootCauses": [
         { "bucket": "proof_gap", "confidence": 0.72, "evidence": ["Specific evidence summary"] }
       ],
-      "actionFamily": "add_proof",
+      "actionFamily": "update_existing_page",
       "operations": ["Add customer proof near the answer block"],
       "priority": "high",
       "confidence": "medium",

package/dist/skillpacks/geo/skills/brand-owned-diagnosis/references/workflow.md

@@ -142,15 +142,18 @@ Use `authority_gap` only when supported by external citation evidence or repeate
 
 Allowed action families:
 
-- `refresh_existing_page`
+- `update_existing_page`
 - `retarget_existing_page`
-- `improve_entity_clarity`
-- `add_proof`
-- `add_comparison_coverage`
-- `fix_technical_issue`
+- `merge_or_redirect_page`
 - `no_action`
 
-Prefer update actions over create actions when an existing discovered page clearly owns the intent.
+Use `update_existing_page` when the owned page is the right surface and needs content, proof, entity clarity, comparison coverage, internal linking, or technical fixes.
+
+Use `retarget_existing_page` when the page is a useful owned surface but should target a different intent or query cluster than the one being evaluated.
+
+Use `merge_or_redirect_page` when the page should not remain an independent surface because it duplicates, cannibalizes, or conflicts with a stronger owned page.
+
+Prefer owned-page updates over generated GEO page creation when an existing discovered page clearly owns the intent.
 
 ### 6. Output
 
@@ -172,7 +175,7 @@ Return a compact diagnosis for each accepted action:
 If a discovered page exists, visibility is low, and the page only gives generic education while competitor pages provide comparison criteria and proof:
 
 - root cause: `comparison_gap`, `proof_gap`
-- action family: `add_comparison_coverage`
+- action family: `update_existing_page`
 - operation: add comparison criteria and customer proof to the existing page
 
 ### Cited But Not Mentioned
@@ -180,7 +183,7 @@ If a discovered page exists, visibility is low, and the page only gives generic
 If the page is cited but the AI answer does not name the tenant brand:
 
 - root cause: `entity_clarity_gap`
-- action family: `improve_entity_clarity`
+- action family: `update_existing_page`
 - operation: strengthen brand naming, publisher schema, and product/company relationship in the answer block
 
 ## Guardrails

package/dist/skillpacks/geo/skills/geo-generating-actions/SKILL.md

@@ -16,65 +16,97 @@ Use these skills for channel-specific diagnosis:
 - `$brand-owned-diagnosis` for customer-owned pages.
 - `$geo-pages-diagnosis` for generated GEO pages.
 - `$third-party-diagnosis` for Earn and external authority work.
+- `$third-party-execution-planning` for selected third-party Earn actions that need human-executable social, directory, review, listing, marketplace, partner, or editorial plans.
+- `$seo-opportunity-audit` for a full SEO opportunity pass when technical, page, SERP, internal-link, or ecommerce SEO evidence is needed.
+- Focused SEO skills for narrow SEO evidence: `$seo-technical-diagnosis`, `$seo-page-diagnosis`, `$seo-serp-opportunity-research`, `$seo-internal-link-opportunity`, and `$seo-ecommerce-opportunity`.
 
 ## Required Reference
 
 Read `references/orchestrator.workflow.md` before final action selection. It contains the full production workflow: context construction, channel invocation order, proposal merge rules, conflict resolution, no-action discipline, and final artifact contract.
 
+Also read shared references when relevant:
+
+- `../../shared/evidence-principles.md` before accepting claim-sensitive,
+  freshness-sensitive, schema/feed, product/SKU, comparison, review, or
+  compliance-sensitive proposals.
+- `../../shared/vertical-playbooks/{vertical}.md` when the tenant vertical is
+  known. Load only matching playbooks, such as `beauty.md`, `saas.md`,
+  `ota.md`, or `commerce.md`; use them as vertical heuristics, not as proof.
+  Tenant-specific strategy in `agent/STRATEGY.md` overrides generic playbooks.
+
 ## Workflow
 
 1. Read host-created run files and stable tenant memory.
-2. Build one compact shared run context.
-3. Invoke or apply the three channel diagnosis skills.
-4. Read channel outputs and reject weak, duplicate, or conflicting proposals.
-5. Prefer no action over low-evidence action.
-6. In local CLI mode, write `agent/runs/{runId}/actions.json` directly.
-7. Write rationale and status files only under the current run path.
-8. Update durable tenant memory only when the run changes stable strategy or repeated learnings.
-
-## Local CLI Mode
+2. Load relevant shared evidence and vertical references only when they affect
+   judgment.
+3. Build one compact shared run context.
+4. Invoke or apply the three channel diagnosis skills.
+5. For selected third-party proposals, invoke or apply `$third-party-execution-planning` before writing final actions.
+6. Persist each channel diagnosis under `agent/runs/{runId}/subagents/` as JSON plus compact `*.rationale.md`.
+7. When SEO evidence is needed, persist SEO skill artifacts under `agent/seo/{skillName}/{runId}/` and reference them from final proposals.
+8. Read channel outputs and reject weak, duplicate, or conflicting proposals.
+9. Prefer no action over low-evidence action.
+10. In hosted remote mode, submit the final artifact with the provided runtime artifact tool. In local mode only, write `agent/runs/{runId}/actions.json` directly.
+11. Write rationale and status files only under the current run path.
+12. Update durable tenant memory only when the run changes stable strategy or repeated learnings.
+
+## Local Skillpack Mode
 
 When running inside a tenant repo, this skill expects a prepared run directory.
 Do not invent a `runId` or create fake input files.
 
-Use the CLI to prepare the same filesystem contract that remote runners use.
+Use the top-level `anymorph` CLI to prepare the same filesystem contract that
+remote runners use. For first-time setup or repair, use `$geo-local-setup`.
 
 ```bash
-anymorph --version
 anymorph status
-anymorph geo init --repo .
-anymorph geo doctor --repo .
-anymorph geo prepare <workspace-domain-or-id> --repo .
+anymorph login
+anymorph init
+anymorph doctor
+anymorph prepare <workspaceId>
 ```
 
-`geo init` installs the bundled skills and local memory scaffold. It does not
-create a strategy run. `geo prepare` fetches the workspace run package from the
-backend and creates the run files.
+`init` installs or syncs the managed skills and local memory scaffold. It does
+not create a strategy run.
+`prepare` fetches the workspace run package from the backend and creates the
+run files.
 
-`geo prepare` creates:
+`prepare` creates:
 
 - `agent/runs/{runId}/manifest.json`
 - `agent/runs/{runId}/context.json`
+- `agent/runs/{runId}/policy.json`
 - `agent/runs/{runId}/intents.json`
+- `agent/runs/{runId}/products.json`
+- `agent/runs/{runId}/intent_products.json`
 - `agent/runs/{runId}/crawl_logs.json`
 - `agent/runs/{runId}/status.json`
 
 `intents.json` comes from `signals.intents` in the backend prepare response.
 It is the same source used by the remote GEO strategy runner.
+For commerce workspaces, `products.json` and `intent_products.json` come from
+the active Product Catalog and IntentProduct mappings.
 
 Inspect prepared intents when needed:
 
 ```bash
-anymorph geo intents {runId} --repo .
+anymorph intents {runId}
 ```
 
 Then run this skill against that `runId`. Use MCP tools only to enrich the
 prepared context or inspect deeper evidence. Do not use MCP calls to replace
 the run package.
 
-For local CLI runs, there is no remote runtime artifact submission tool. The
-final artifact contract is the filesystem contract:
+For local runs, there is no hosted runtime artifact submission tool. The final
+artifact contract is the same JSON object shape the remote submit tool accepts,
+but persisted through the filesystem:
 
+- write `agent/runs/{runId}/subagents/brand_owned.json`
+- write `agent/runs/{runId}/subagents/brand_owned.rationale.md`
+- write `agent/runs/{runId}/subagents/geo_pages.json`
+- write `agent/runs/{runId}/subagents/geo_pages.rationale.md`
+- write `agent/runs/{runId}/subagents/third_party.json`
+- write `agent/runs/{runId}/subagents/third_party.rationale.md`
 - write `agent/runs/{runId}/actions.json`
 - write `agent/runs/{runId}/rationale.md`
 - update `agent/runs/{runId}/status.json`
@@ -82,19 +114,75 @@ final artifact contract is the filesystem contract:
 After writing artifacts, validate them with:
 
 ```bash
-anymorph geo validate {runId} --repo .
+anymorph validate {runId}
+```
+
+Then commit and push the tenant repo artifacts, and submit the run to backend:
+
+```bash
+git add agent/runs/{runId} agent/STRATEGY.md agent/LEARNINGS.md
+git commit -m "chore: add geo strategy run {runId}"
+git push origin main
+anymorph submit {runId}
 ```
 
+`submit` registers or updates the backend run as `proposed`, reads
+`agent/runs/{runId}/actions.json` from the tenant repo, and immediately
+materializes it in Dashboard. There is no separate approve step.
+
+### Adding Actions After a Run Is Submitted
+
+A submitted run is immutable. Once `submit` succeeds the backend locks the run
+as `executed`, so re-submitting the same `runId` — even after editing
+`actions.json` and pushing again — is a silent no-op: it returns `executed`
+without re-reading the file or materializing anything.
+
+To add or change actions, do not edit an executed run. Run a fresh `prepare` to
+get a new `runId`, write the actions under that new run directory, then
+`validate`, commit, push, and `submit` the new run.
+
+Put only the new actions in the new run unless you intend to re-materialize the
+prior set. Materialize is additive, not a declarative replace: `third_party` and
+`brand_owned` actions create new rows on every run (the prior run's rows stay
+`open`), while `geo_page` actions upsert by slug (the same slug is re-queued for
+generation).
+
 Only use runtime artifact tools when the host environment explicitly provides
 them. In ordinary local tenant repo work, the filesystem artifacts above are the
 source of truth.
 
+## Contract Guardrails
+
+Write `agent/runs/{runId}/actions.json` exactly to the production contract in
+`apps/shared-contracts/src/index.cjs` plus the backend business rules in
+`apps/backend/src/modules/geo-strategy/geo-strategy-action.schema.ts`.
+
+- The artifact root is strict. Use only `schemaVersion`, `runId`, `policy`, and `actions`. Never add `artifactPaths` to `actions.json`; that belongs only to submit transport.
+- Each action is strict. Include `id`, `operation`, `surface`, `assetType`, `intentId`, `target`, `objective`, `changeBrief`, `reason`, `expectedOutcome`, `evidence`, `priority`, and `confidence`; do not add extra keys.
+- Each `evidence[]` item is strict: `{ "type": "signal" | "workspace" | "source" | "research", "ref": "...", "summary": "..." }`.
+- `target` is strict. Allowed keys are only `pageId`, `url`, `title`, `description`, `queryCluster`, `sourceDomain`, `suggestedSlug`, `pageRole`, and `targetProductIds`. Never use `target.domain`; use `target.sourceDomain` for third-party domains.
+- `brand_owned` target may use `pageId` or `url`; do not include `pageRole`, `suggestedSlug`, `sourceDomain`, or `targetProductIds`.
+- `geo_page` create target must use root-relative `suggestedSlug` or `url` plus `title`; do not include `pageId` or `sourceDomain`.
+- `geo_page` update target may use `pageId` or `url`; do not include `pageRole`, `suggestedSlug`, `sourceDomain`, or `targetProductIds`.
+- `third_party` target must use `sourceDomain` or absolute http(s) `url`; do not include `pageId`, `pageRole`, `suggestedSlug`, or `targetProductIds`.
+
 ## Final Decision Rules
 
 - Emit at most 20 actions.
 - Use only `create` or `update` operations.
+- Use `surface: "on_page"` for `brand_owned` and `geo_page`.
+- Use `surface: "off_page"` for `third_party`.
 - Use `brand_owned` only for customer-owned discovered pages.
+- Use `brand_owned` only with `operation: "update"`.
 - Use `geo_page` only for generated or managed GEO page work.
 - Use `third_party` only for off-page Earn work.
 - Every action must include either an existing `intentId` or a non-null `proposedIntent`.
+- If `intentId` is a string, omit `proposedIntent`; do not set it to null.
+- `geo_page` create actions must include a root-relative `target.suggestedSlug` or `target.url` and `target.title`.
+- For commerce workspace `geo_page` create actions, include 1-5 `target.targetProductIds` from `products.json` or `intent_products.json`.
+- Do not emit commerce `geo_page` create actions when no catalog product evidence fits the intent.
 - Third-party actions must name the exact domain and, when known, the exact publish surface.
+- Third-party `changeBrief` must include the surface, format, angle, and concrete execution steps.
+- Third-party actions for directory, review, listing, marketplace, partner, open-listicle, social, or owned-profile work should be based on `$third-party-execution-planning` output when the diagnosis proposal is selected.
+- When using `$third-party-execution-planning`, derive the final action from its work-order fields: `executionType`, `surfaces`, `requiredAssets`, `policyChecks`, `executionSteps`, `completionSignal`, `impactSignal`, and `fallback`.
+- For third-party final actions, fold `executionType`, required assets, policy checks, operator steps, and fallback into `changeBrief`; use `completionSignal` and `impactSignal` to write `expectedOutcome`.

package/dist/skillpacks/geo/skills/geo-generating-actions/references/orchestrator.workflow.md

@@ -19,6 +19,7 @@ It is the final decision-maker for the run.
 
 - `agent/runs/{runId}/context.json`
 - `agent/runs/{runId}/manifest.json`
+- `agent/runs/{runId}/policy.json`
 - `agent/runs/{runId}/intents.json`
 - `agent/BRAND.md`
 - `agent/STRATEGY.md`
@@ -104,11 +105,45 @@ It should include:
 - relevant brand constraints
 - strategy priorities from `STRATEGY.md`
 - last-week performance summary
-- recent action exclusion mask
+- recent action exclusion mask (derived from `signals.priorDecisions` — see below)
 - candidate intent/page/domain slices
 - evidence budget
 - output schema
 
+#### Building the exclusion mask
+
+The authoritative source is the top-level `signals.priorDecisions[]` array — it holds every active decision (intent-anchored, url-anchored, AND sourceDomain-anchored, including domain-only third-party rejections that have no intent/page to attach to). Match candidates against this array.
+
+`signals.intents[].priorDecisions` and `signals.pages[].priorDecisions` are a pre-grouped convenience mirror (the same decisions, attached to the intent/page they anchor on) — use them as a shortcut, but do not rely on them as the only source, since domain-only decisions appear only in the top-level array.
+
+A prior decision is a match when its `match` object aligns with the candidate on all present fields:
+
+```
+match key = { intentId, assetType, operation, target }
+```
+
+For each candidate, look up matches in `signals.priorDecisions[]` by comparing:
+
+- the candidate's resolved `intentId` against the intent the decision is attached to (via `signals.intents[].priorDecisions`), and
+- the decision's `match` fields against the candidate: `assetType`, `operation`, and the `target` fields `url`, `queryCluster`, `sourceDomain`, or `suggestedSlug`.
+
+Match on any non-null subset (a domain-level third-party decision matches a candidate that targets the same `sourceDomain`).
+
+Apply the mask as follows:
+
+- **`reasonClass: "durable_exclusion"` with `n ≥ 2`** — suppress the candidate entirely.
+  Do not pass it to any channel diagnosis.
+  Record in `rationale.md`: the intentId/target, `reasonClass`, `reasonTags`, the human `reason` text (if present), and `n` (number of times dismissed/rejected).
+
+- **`reasonClass: "fixable_critique"` (any `n`)** — keep the candidate but pass the prior critique to the channel diagnosis as a constraint.
+  The diagnosis must address the critique (e.g. revise tone, adjust value proposition, change timing) rather than reproducing the previously rejected form.
+  Record in the channel rationale that the candidate was revised to address a prior critique, citing `reasonTags` and `reason`.
+
+- **`reasonClass: "durable_exclusion"` with `n = 1`** — treat as a soft signal.
+  Pass the candidate with a note that it was dismissed once; the channel diagnosis may still include it if evidence is strong, but must acknowledge the prior dismissal in its rationale.
+
+If `priorDecisions` is absent or empty for an intent, proceed normally.
+
 This context is shared by all three channel diagnoses.
 
 Channel diagnoses may receive channel-specific candidate slices, but they should share the same strategic baseline.
@@ -120,8 +155,28 @@ Apply these channel skills directly:
 - `brand-owned-diagnosis`
 - `geo-pages-diagnosis`
 - `third-party-diagnosis`
+- `third-party-execution-planning`
+- `seo-opportunity-audit`
+- `seo-technical-diagnosis`
+- `seo-page-diagnosis`
+- `seo-serp-opportunity-research`
+- `seo-internal-link-opportunity`
+- `seo-ecommerce-opportunity`
 
 Each channel diagnosis returns one compact proposal set to the lead agent.
+SEO diagnosis skills return supporting evidence and action candidates under
+`agent/seo/{skillName}/{runId}/`. Use those artifacts to support final GEO
+actions, but the lead agent still owns final action selection and submission.
+Persist every channel diagnosis before final judging:
+
+- `agent/runs/{runId}/subagents/brand_owned.json`
+- `agent/runs/{runId}/subagents/brand_owned.rationale.md`
+- `agent/runs/{runId}/subagents/geo_pages.json`
+- `agent/runs/{runId}/subagents/geo_pages.rationale.md`
+- `agent/runs/{runId}/subagents/third_party.json`
+- `agent/runs/{runId}/subagents/third_party.rationale.md`
+
+The JSON files are the mergeable source of truth. The rationale files should be compact decision logs: accepted, rejected, uncertain, missing evidence, and cross-channel concerns. Do not paste raw transcripts.
 
 Expected channel diagnosis output:
 
@@ -143,7 +198,7 @@ Expected channel diagnosis output:
           "evidence": ["Evidence summary"]
         }
       ],
-      "actionFamily": "refresh_existing_page",
+      "actionFamily": "update_existing_page",
       "operations": ["Add proof section"],
       "priority": "high",
       "confidence": "medium",
@@ -171,18 +226,59 @@ Expected channel diagnosis output:
 Channel diagnoses must not include `workspaceId`, `runId`, `channel`, final action id, final `assetType`, or final URL.
 The orchestrator derives final action ids, channel-to-asset mapping, and executable action shape.
 
+For selected `third_party` proposals, apply `third-party-execution-planning`
+before final action writing. Diagnosis decides whether an external opportunity
+is worth considering; execution planning turns the selected opportunity into a
+human-executable plan for social surfaces and non-social surfaces such as
+directories, review sites, marketplaces, partner pages, open listicles,
+editorial inclusion pages, and owned third-party profiles.
+
 ### 5. Judge Channel Outputs
 
-The orchestrator reviews all proposals.
+The orchestrator reads the three persisted channel JSON files and rationale files, then reviews all proposals.
 
 It should ask:
 
 - Does this proposal match tenant strategy?
 - Is the evidence strong enough?
 - Is it redundant with another channel's proposal?
-- Is it suppressed by recent actions?
+- Is it suppressed by recent actions? (see priorDecision check below)
 - Is the action executable by the current product surface?
 - Is it more important than competing proposals this week?
+- For generated-page updates, is the page old enough to evaluate, indexed, or backed by a concrete non-performance defect?
+
+#### priorDecision check (per proposal)
+
+For each proposal returned by a channel diagnosis, derive its match key:
+
+```
+{ intentId, assetType, operation, target: { url?, queryCluster?, sourceDomain?, suggestedSlug? } }
+```
+
+Look up matching entries in the authoritative top-level `signals.priorDecisions[]` array. A decision matches when its `match` object aligns with the proposal on all present fields — `assetType`, `operation`, and the `target` fields `url`, `queryCluster`, `sourceDomain`, or `suggestedSlug` (a domain-only third-party decision matches a proposal targeting the same `sourceDomain`), plus the `intentId` the decision is attached to (via `signals.intents[].priorDecisions`). The `signals.intents[].priorDecisions` and `signals.pages[].priorDecisions` attachments are a convenience shortcut for intent- and url-anchored proposals; the top-level array is the source of truth and the only place domain-only decisions appear.
+
+Apply the following rules and record the outcome in `rationale.md`:
+
+1. **Suppress** — if any matching prior decision has `reasonClass: "durable_exclusion"` and `n ≥ 2`:
+   reject the proposal; do not emit it as a final action.
+   In `rationale.md` write: `SUPPRESSED — durable exclusion: <reasonTags> (n=<n>). Prior reason: "<reason>".`
+
+2. **Revise** — if any matching prior decision has `reasonClass: "fixable_critique"`:
+   keep the proposal but require that the final action explicitly addresses the critique.
+   Update `changeBrief` and `objective` to reflect the correction.
+   In `rationale.md` write: `REVISED — fixable critique: <reasonTags>. Addressed by: <description of correction>.`
+
+3. **Soft flag** — if any matching prior decision has `reasonClass: "durable_exclusion"` and `n = 1`:
+   the proposal may proceed, but record: `SOFT FLAG — dismissed once: <reasonTags>. Proceeding because <reason for override>.`
+
+4. **No prior decisions** — proceed normally; no rationale entry required for this check.
+
+Fresh generated-page guard:
+
+- If a generated page was published less than 7 days ago, do not emit a `geo_page` update based only on low visibility, zero traffic, zero GSC impressions, or zero AI citations.
+- For fresh generated pages, accept an update only when the proposal identifies a concrete non-performance defect: wrong intent, broken route, crawl/indexation blocker, duplicate/cannibalization, missing brand/entity clarity, or factual/product-claim defect.
+- If a generated page is not indexed after 7 days, keep the issue in analysis and flag it as indexation/technical evidence. Prefer a technical follow-up or monitor note over a content update unless the content itself is also defective.
+- When rejecting a premature generated-page update, record the page id/URL and the next reasonable evaluation window in `rationale.md` or the channel rationale.
 
 The orchestrator may:
 
@@ -225,11 +321,20 @@ Guardrail:
 - `brand_owned` is only for customer-owned discovered pages.
 - Do not send Anymorph-generated, recommended, preview-only, or unpublished GEO pages to Fix.
 - Existing generated page work must stay `assetType: "geo_page"` even when the proposed operation is a technical fix or content iteration.
+- Do not emit a `geo_page` update for a generated page published less than 7 days ago unless there is a concrete non-performance defect.
+- Do not treat missing performance data on a fresh generated page as proof of weakness.
+- Do flag a generated page that is not indexed after 7 days, but keep indexation analysis separate from content iteration unless both are supported by evidence.
 
 ### 8. Write Artifacts
 
 Write:
 
+- `agent/runs/{runId}/subagents/brand_owned.json`
+- `agent/runs/{runId}/subagents/brand_owned.rationale.md`
+- `agent/runs/{runId}/subagents/geo_pages.json`
+- `agent/runs/{runId}/subagents/geo_pages.rationale.md`
+- `agent/runs/{runId}/subagents/third_party.json`
+- `agent/runs/{runId}/subagents/third_party.rationale.md`
 - `agent/runs/{runId}/actions.json`
 - `agent/runs/{runId}/rationale.md`
 - `agent/runs/{runId}/status.json`
@@ -249,12 +354,29 @@ must not edit it. If a brand fact looks wrong, raise it in
 
 ## Final Action Contract
 
-Each final action must include:
+Write `agent/runs/{runId}/actions.json` to the exact production contract.
+The Zod source of truth is `apps/shared-contracts/src/index.cjs`; the
+asset-type target business rules are in
+`apps/backend/src/modules/geo-strategy/geo-strategy-action.schema.ts`.
+
+The artifact root is strict. It must contain only:
 
+- `schemaVersion: 1`
+- `runId`
+- `policy`, matching `agent/runs/{runId}/policy.json`
+- `actions`, with at most 20 items
+
+Do not add root-level helper fields such as `artifactPaths`. `artifactPaths`
+belongs only to submit transport, never to `actions.json`.
+
+Each final action is strict. It must contain only:
+
+- `id`
 - `operation`
 - `surface`
 - `assetType`
 - `intentId`
+- `proposedIntent`, only when `intentId` is null
 - `target`
 - `objective`
 - `changeBrief`
@@ -264,6 +386,50 @@ Each final action must include:
 - `priority`
 - `confidence`
 
+Each `evidence[]` item is strict:
+
+- `type`: one of `signal`, `workspace`, `source`, `research`
+- `ref`: non-empty string
+- `summary`: non-empty string
+
+`target` is strict. Allowed target keys are only:
+
+- `pageId`
+- `url`
+- `title`
+- `description`
+- `queryCluster`
+- `sourceDomain`
+- `suggestedSlug`
+- `pageRole`
+- `targetProductIds`
+
+Never use `target.domain`. For external domains, use `target.sourceDomain`.
+
+Additional action rules:
+
+- `brand_owned` uses `operation: "update"` and `surface: "on_page"`.
+- `brand_owned` target must include `pageId` or `url`; do not include `pageRole`, `suggestedSlug`, `sourceDomain`, or `targetProductIds`.
+- `geo_page` uses `surface: "on_page"`.
+- `third_party` uses `surface: "off_page"`.
+- If `intentId` is a string, omit `proposedIntent`.
+- If `intentId` is null, include `proposedIntent.name` and `proposedIntent.reason`.
+- `geo_page` create actions must include a root-relative `target.suggestedSlug` or `target.url`, plus `target.title`.
+- `geo_page` create target must not include `pageId` or `sourceDomain`.
+- `geo_page` update target must include `pageId` or `url`; do not include `pageRole`, `suggestedSlug`, `sourceDomain`, or `targetProductIds`.
+- For commerce `geo_page` create actions, use `target.targetProductIds` only from product evidence in `products.json`, `intent_products.json`, or `get_intent_products`.
+- Third-party `changeBrief` must name the publish surface, content format, content angle, and concrete execution steps.
+- Third-party target must include `sourceDomain` or absolute http(s) `url`; do not include `pageId`, `pageRole`, `suggestedSlug`, or `targetProductIds`.
+- Third-party `target.url` should be the exact execution surface when known: social thread/channel/profile, directory listing or submission page, review profile/category page, marketplace or partner page, open listicle/editorial page, or owned third-party profile.
+- Third-party `operation` should be `create` for new external presence, inclusion requests, review collection motions, or owned-channel content; use `update` for existing listing/profile refreshes or factual corrections.
+- Third-party `expectedOutcome` should name one observable result: listing/profile update, submission acknowledgement, review motion launched, editorial acknowledgement/update, creator mention, indexed post, or citation movement.
+- When a `third_party` action uses `third-party-execution-planning`, derive final fields from the work order:
+  - `target.url` from the most actionable `surfaces[].url`.
+  - `target.sourceDomain` from that surface URL's domain.
+  - `operation` from `executionType` and the decision matrix.
+  - `changeBrief` from `executionType`, `whyThisSurface`, `requiredAssets`, `policyChecks`, `executionSteps`, and `fallback`.
+  - `expectedOutcome` from `completionSignal` plus `impactSignal`.
+
 ## Guardrails
 
 - Do not let a channel diagnosis proposal pass through automatically.