anymorph 0.4.0 → 0.5.0

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

@@ -1,188 +0,0 @@
----
-name: geo-generating-actions
-description: Use when generating recurring or on-demand GEO strategy actions from tenant memory, run context, channel diagnoses, and evidence-backed opportunity candidates.
----
-
-# GEO Generating Actions
-
-Use this skill to orchestrate GEO action generation.
-
-This skill owns the final decision. Channel diagnosis should be handled by product diagnosis skills, then merged and judged here.
-
-## Channel Skills
-
-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. 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 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 status
-anymorph login
-anymorph init
-anymorph doctor
-anymorph prepare <workspaceId>
-```
-
-`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.
-
-`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 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 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`
-
-After writing artifacts, validate them with:
-
-```bash
-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/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "GEO Generating Actions"
-  short_description: "Generate final GEO strategy actions from channel diagnoses."
-  default_prompt: "Use $geo-generating-actions to generate final GEO strategy actions for this workspace."

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

@@ -1,440 +0,0 @@
-# Orchestrator Workflow
-
-## Role
-
-The orchestrator owns the weekly GEO strategy run.
-
-It does four things:
-
-1. Analyze last week's performance.
-2. Combine performance with tenant strategy into one common run context.
-3. Run all three channel diagnoses with that common context.
-4. Judge the returned proposals and write the final action list.
-
-The orchestrator is not just a router.
-
-It is the final decision-maker for the run.
-
-## Inputs
-
-- `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`
-- `agent/LEARNINGS.md`
-- prior `agent/runs/*` summaries when useful
-- `schemaCatalog`
-- `signals`
-- `geo_*` query surface
-
-## Required Views
-
-Use these views when available:
-
-- `geo_intent_coverage`
-- `geo_recommendation_quadrants`
-- `geo_page_intent_visibility_gaps`
-- `geo_page_performance`
-- `geo_strategy_actions_recent`
-- `geo_pages`
-- `geo_intents`
-
-Use these when third-party analysis is enabled:
-
-- `geo_intent_citations`
-- `geo_third_party_domains`
-- `geo_competitor_citations`
-- `geo_third_party_sentiment`
-
-If a view is unavailable, continue with lower confidence and record the missing view in `rationale.md`.
-
-## Workflow
-
-### 1. Load Stable Tenant Context
-
-Read:
-
-- `agent/BRAND.md`
-- `agent/STRATEGY.md`
-- `agent/LEARNINGS.md`
-- recent prior run artifacts
-
-Extract:
-
-- current tenant priorities
-- explicit channel preferences
-- forbidden actions
-- recent bets
-- repeated learnings
-- open questions
-
-Do not rewrite tenant memory in this phase.
-
-### 2. Analyze Last Week's Performance
-
-Build a concise performance summary for the run.
-
-Use:
-
-- visibility changes
-- weak intents
-- covered-but-weak intents
-- recommendation quadrant changes
-- page performance changes
-- citation/domain changes
-- prior action outcomes when available
-
-The summary should answer:
-
-- What improved?
-- What regressed?
-- Which intents remain weak?
-- Which existing pages are underperforming?
-- Which pages or intents look healthy enough to avoid touching?
-- Which prior actions should suppress repeats?
-
-### 3. Build Common Run Context
-
-Create one shared context object for all channel diagnoses.
-
-It should include:
-
-- tenant objective for this run
-- relevant brand constraints
-- strategy priorities from `STRATEGY.md`
-- last-week performance summary
-- 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.
-
-### 4. Run Three Channel Diagnoses
-
-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:
-
-```json
-{
-  "summary": "Short channel-level diagnosis.",
-  "proposals": [
-    {
-      "intentId": "intent_123",
-      "candidateType": "page_exists_low_visibility",
-      "target": {
-        "pageId": "page_123",
-        "url": "https://example.com/page"
-      },
-      "rootCauses": [
-        {
-          "bucket": "proof_gap",
-          "confidence": 0.72,
-          "evidence": ["Evidence summary"]
-        }
-      ],
-      "actionFamily": "update_existing_page",
-      "operations": ["Add proof section"],
-      "priority": "high",
-      "confidence": "medium",
-      "evidence": [
-        {
-          "type": "signal",
-          "ref": "geo_recommendation_quadrants:intent_123",
-          "summary": "mentioned_not_recommended_rate is high"
-        }
-      ],
-      "whyNow": "Why this should be considered this week.",
-      "risks": ["Possible risk or uncertainty"]
-    }
-  ],
-  "rejected": [
-    {
-      "ref": "intent_456",
-      "reason": "Suppressed by recent action mask"
-    }
-  ],
-  "noActionRationale": "Optional. Use when proposals is empty."
-}
-```
-
-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 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? (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:
-
-- accept
-- merge
-- downgrade
-- reject
-- move to `rationale.md` only
-
-### 6. Resolve Cross-Channel Conflicts
-
-Common conflicts:
-
-- `brand_owned` proposes refreshing a page while `geo_pages` proposes creating a new page for the same intent.
-- `geo_pages` proposes iteration while `third_party` argues authority is the bottleneck.
-- `third_party` proposes outreach but owned page coverage is clearly weak.
-
-Default resolution:
-
-1. If an existing page clearly owns the intent and content gaps are fixable, prefer updating it.
-2. If no page exists, prefer GEO page generation unless tenant strategy says customer-site page first.
-3. If page content is strong but external validation is the bottleneck, keep third-party as a candidate.
-4. If evidence is weak, do not emit an action; record the uncertainty.
-
-### 7. Build Final Action List
-
-Select at most 20 final actions.
-
-Prefer:
-
-1. high-confidence fixes for existing important pages
-2. high-confidence generated GEO page iteration
-3. high-confidence net-new page generation
-4. third-party actions only when actionability is clear
-
-Low-confidence findings go to `rationale.md`.
-
-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`
-
-Optionally archive compact observations in:
-
-- `agent/archive/{time5}-{slug}.json`
-
-Update stable memory only when the run changes durable tenant strategy.
-On bootstrap runs, also update stable memory when `agent/STRATEGY.md` or
-`agent/LEARNINGS.md` is missing, blank, or still scaffold-only.
-
-`agent/BRAND.md` is backend-managed. It is regenerated from the workspace
-brand record whenever the `brandHash` frontmatter drifts, and the agent
-must not edit it. If a brand fact looks wrong, raise it in
-`rationale.md` rather than editing the file.
-
-## Final Action Contract
-
-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`
-- `reason`
-- `expectedOutcome`
-- `evidence`
-- `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.
-- Do not choose duplicate actions for the same intent unless they are clearly complementary.
-- Do not invent final routes for create actions.
-- Do not treat missing data as proof.
-- Do not diagnose authority from low visibility alone.
-- Do not update tenant memory with generic SEO/GEO advice.