Align Docs Scope Gates — Autonomous Agents Agentic Workflow

schema_version: 1
id: agent_docs_scope
title: "Align Docs Scope Gates"
description: "Sweep the account's skill packs for freshness and resolve the docs type's five scope gates from that sweep — user inputs, then workspace context, then the platform floor — and publish all five together as the job's result"
overview: |
  The scope phase of a docs-site goal. The SD agent reads the goal and the site it targets, grounds
  itself in the site's DOCS-INSTRUCTION instance and the account's skill-pack registry, then sweeps
  every pack for freshness and aligns the type's five docs gates: source allowlist · staleness ledger
  · confidence floor · sitemap draft · deploy target. Each gate resolves from the user inputs first,
  then the workspace context, then the platform floor — recording per gate the value, the source, and
  the arm used.

  The sweep is what makes this a docs job rather than a generic scope pass: the allowlist is explicit
  (a pack dir absent from the registry's index.json is out by construction) and carves per module and
  per site; the ledger dates each source down an evidence ladder — pinned commit anchors, then a repo
  diff, then age; and a content source under the confidence floor earns a skill-refresh need, not a
  page pass. Gates are the job's RESULT, published all five together with the ledger and the sitemap
  draft attached — they never fill in one by one. On a re-run only the gates that read a changed input
  re-derive; a gate the user set stays theirs, and all five are published regardless. Anchored on the
  portal goal URL, not a ticket: no issue exists at this phase (the site's epic is created later, when
  the decide phase's decisions lock).

category:
  level: pipeline
  domain: engineering

metadata:
  agent: true
  role: sd
  # Gate-verdict vocabulary for portal playbook steps (PLAYBOOKS.md §5) — matched from the
  # job's published result; declaring it here is what makes this workflow content-routable.
  verdicts: [GATES_ALIGNED, NEEDS_INPUTS]

params:
  agentic_app:
    type: string
    default: "cc"
    description: "Agent-app slug selecting the per-run env file ~/.agent-env.d/<slug> (AAP-C); 'cc'/subscription clears provider vars"
  goal_url:
    type: string
    description: "Portal goal URL — the typed goal whose target site this job scopes (no ticket exists at this phase)"
  hint:
    type: string
    default: ""
    description: "Optional extra instructions for the agent (on a rework run, the gate values so far — user-set ones marked '(yours — keep)')"
  entry_path:
    type: string
    default: "~/workspace"
    description: "Working directory for the agent"

steps:
  - type: terminal.open
    title: "Agent: SD Docs Scope"
    cwd: "{{entry_path}}"
  - type: terminal.run
    cmd: |
      source ~/.agent-env
      # Provider clear-set (AAP-C SCRUM-1506 + AAP-17 SCRUM-1653): identical to every agents/ops/*.yaml
      # preamble; scripts/check-ops-clearset.mjs guards this list against AGENT_APP_ENV_KEYS drift.
      unset \
        ANTHROPIC_API_KEY ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN CCR_CONFIG_B64 \
        CLAUDE_CODE_USE_BEDROCK AWS_REGION AWS_PROFILE ANTHROPIC_MODEL \
        ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION ANTHROPIC_SMALL_FAST_MODEL CLAUDE_CODE_MAX_OUTPUT_TOKENS \
        CLAUDE_CODE_USE_VERTEX CLOUD_ML_REGION ANTHROPIC_VERTEX_PROJECT_ID ANTHROPIC_VERTEX_BASE_URL \
        CLAUDE_CODE_USE_FOUNDRY ANTHROPIC_FOUNDRY_RESOURCE ANTHROPIC_FOUNDRY_BASE_URL \
        ANTHROPIC_DEFAULT_OPUS_MODEL ANTHROPIC_DEFAULT_SONNET_MODEL ANTHROPIC_DEFAULT_HAIKU_MODEL
      if [ -f "$HOME/.agent-env.d/{{agentic_app}}" ]; then
        source "$HOME/.agent-env.d/{{agentic_app}}"
      fi
      claude --dangerously-skip-permissions "$(cat <<'SB_PROMPT'
      read the goal and the site it targets - the brief, every attached file and every link - {{goal_url}}. if anything fails to load, stop and report the error.
      READ - the goal's own state comes from the portal, not from the page:
        - your job identity is in ~/.sidebutton/job-context.json (the .session_id field); the portal base URL is $PORTAL_URL and your token is $SIDEBUTTON_AGENT_TOKEN, both already in ~/.agent-env.
        - GET "$PORTAL_URL/api/agents/goal/read?session_id=<your session_id>" with the header "Authorization: Bearer $SIDEBUTTON_AGENT_TOKEN". it answers with the goal, the current phase, every phase's state, the gates as they stand now, and the intake files and links.
        - fetch each intake file by name from "$PORTAL_URL/api/agents/goal/file?name=<name>&session_id=<your session_id>" with the same header - read returns names, never bytes.
      EXECUTION RULES (read first - they override any habit):
      - Do ALL of the work in THIS session, in the FOREGROUND, and finish before your turn ends. You MAY spawn subagents (the Agent / Task tool) or run parallel searches to investigate faster - but you MUST wait for every subagent and any background task to return and fold their results in YOURSELF before ending the turn. Never move the work (or the result) into the background - no run_in_background, no background workflows, no trailing & - and then end the turn expecting to be resumed. Ending your turn is FINAL here: nothing wakes you to "resume", so a turn that ends while a spawned subagent or any background work is still pending is reported as a FAILED step, not a pause.
      - Publish the result YOURSELF, in the foreground, as the LAST thing you do - after every subagent and background task has returned. Never delegate it to a subagent, and never end the turn "holding", "pausing", or planning to "resume/continue later". If you genuinely cannot finish, say so in the result and stop.
      learn the area first - ground yourself in the skills this job carries: the sd role playbook, the target site's DOCS-INSTRUCTION instance, the account's skill-pack registry (its index.json, each pack's skill-pack.json, and the frontmatter of every _skill.md), and the ops contract for publishing to a goal.
      sweep the account's packs for freshness and align the docs type's five scope gates - source allowlist / staleness ledger / confidence floor / sitemap draft / deploy target:
        - the allowlist is explicit - a pack dir present in the registry folder but absent from index.json is out by construction - and the carve is per module and per site: content source, audit source, or never-content
        - date every source down an evidence ladder: pinned commit anchors first (aligned_against_commit / verified_against_commit, diffed to HEAD over the module's mapped paths), then a repo diff where the pack declares repos, then the module's own last_verified date - stale once it is more than 30 days old
        - an index.json version that differs from the pack's own skill-pack.json is unreconciled, therefore not fresh - a pack that sets needs_reverification true is stale until it is refreshed, and an absent needs_reverification is not an assertion of freshness
        - hold every content source to the confidence floor (0.70 unless the goal sets another): a module below it earns an improve-mode skill-refresh need on that gate, not a page pass
        - draft the sitemap from the module inventory - module structure approximates the natural sitemap - and declare the coverage gaps you leave
        - resolve each gate from the user inputs FIRST, then the workspace context, then the platform floor - the floor for the deploy target is a SideButton-hosted docs subdomain
        - write per gate: the value, the source it came from, and the arm it resolved on - the exact token user-input, workspace or platform-floor, or null for a gate that still needs you
        - a gate you cannot resolve becomes a question with a recommendation - nothing blocks silently
      validate rather than author where the site already has a hand-written DOCS-INSTRUCTION instance: report what that instance already settles, and name every place the sweep disagrees with it.
      act idempotently and delta-aware: on a re-run a gate the user set stays theirs - it is an input now - so re-derive only the gates that read an input that changed and carry the rest forward verbatim, but publish all five either way.
      create no issues, dispatch nothing and refresh no packs: scope is alignment, and the wave-0 refreshes the ledger calls for are the plan phase's job.
      {{hint}}
      PUBLISH - your final foreground action, and the ONLY channel the portal renders gates from:
        - POST "$PORTAL_URL/api/agents/goal/gates?session_id=<your session_id>" with the headers "Authorization: Bearer $SIDEBUTTON_AGENT_TOKEN" and "Content-Type: application/json", and this body shape:
      {"verdict":"<the same token you end on>","gates":[{"id":"source-allowlist","content":"the packs and the modules inside them that feed this site, carved per module","arm":"workspace"}]}
        - the five ids are fixed and are the whole set: source-allowlist, staleness-ledger, confidence-floor, sitemap-draft, deploy-target. arm is exactly one of user-input, workspace, platform-floor, or null.
        - it is ALL OR NOTHING: send all five in ONE delivery, exactly once each - gates never fill in one by one. a partial, duplicated or unknown set is a 422 naming expected/missing/unknown/duplicates and it writes NOTHING, so on a rework re-derive selectively but publish completely. keep the body under 256 KB and the verdict under 64 characters.
        - check the status, because a refused publish looks exactly like a delivered one from inside your session: 2xx is the only delivered outcome. 409 means your job is no longer the goal's live scope job, 403 that the session id resolved no phase, 400 a refused body, 422 an incomplete set, 413 over 256 KB. on anything other than 2xx the phase has recorded NO verdict and will never advance - fix the body and retry here, and if it still will not land, say so in your result and do NOT end on a success token.
        - read the response: published are the gates you just wrote; kept are the ones a human had already edited, left exactly as they stand - a gate you re-state under a user's edit comes back kept, and that is success, not a rejection.
        - prose is not the channel. a gate that only appears in your written result never renders on the goal page - POST first, then write the result.
        - then attach staleness-ledger.md and sitemap-draft.md as run artifacts, and write the ledger, the sitemap draft and the per-gate value/source/arm as this job's result.
      end with one line - "VERDICT:" followed by exactly one of GATES_ALIGNED (every gate resolved or safely defaulted) / NEEDS_INPUTS (a gate needs something only the user has - name each one and what it unblocks) - and use these uppercase tokens nowhere else.
      SB_PROMPT
      )"