ah-2lh Claim-time Yonote artifact materialization into .task/artifacts/ + prompt manifest Past Stand

Why: the operator authors specs/big documents in Yonote and wants task cards to reference them by URL; the claimed agent must see the CURRENT doc content without the repo ever carrying it. What: optional yonote config block (base_url, token via ${YONOTE_TOKEN} from /etc/agent-hub/env, claim_budget); at claim, scan the frontmatter-stripped description body for https://<yonote-host>/doc/<seg> URLs (works on both raw-markdown and Vikunja TipTap-HTML descriptions), resolve via documents.info, export markdown (with .text fallback), write .task/artifacts/<NN>-<slug>.md via StartSpec.Artifacts in prepareTaskDir, append a '## Reference documents' manifest to the prompt, add an artifacts count to the claim comment + an event. Dead references NEVER fail the claim; every attempt re-exports fresh. wave 2.5 — implement after feat/wave2-archive-links merges. Depends on ah-gxa (client).

# Claim-time Yonote artifact materialization

Operator authors specs/big docs in Yonote; a task card references them by URL; at claim the
daemon exports each referenced doc to `.task/artifacts/<NN>-<slug>.md` in the worktree and lists
them in the prompt. `.task/` is git-excluded (excludeTaskDir) and archived to tar.gz at Done, so
artifacts never touch the repo.

## Config (internal/config)

New OPTIONAL top-level block, feature fully inert when absent (telegram/ntfy presence pattern):

    yonote:
      base_url: "https://bigbes.yonote.ru"   # required when present; validateHTTPURL
      token: "${YONOTE_TOKEN}"               # required when present; BOT token (see client bead runbook); ${VAR} from /etc/agent-hub/env via existing expandEnv
      claim_budget: "90s"                    # optional; TOTAL wall clock for all exports in one claim; default 90s; positive (parseDuration)

`Yonote{BaseURL, Token string; ClaimBudget time.Duration}` + `present()` (trimmed BaseURL or Token
non-empty) + validation (both required when present; URL check; strict KnownFields comes free from
rawConfig). Trim trailing "/" off BaseURL at resolve (AgentsView precedent).
Wiring (internal/deps or cmd wiring, wherever mem0/vikunja clients are built): when present →
`yonote.New(BaseURL, Token)`; call AuthInfo once at startup: log identity, WARN if !IsBot; a
startup AuthInfo FAILURE logs an error and continues — Yonote outage must never block board work.

## Reference convention (DECISION)

Every substring of the card description matching `https?://<host-of-base_url>/doc/<seg>` is a
reference; `<seg>` = last path segment `[A-Za-z0-9._~-]+` (query/fragment excluded by charset).
Extraction runs over the frontmatter-STRIPPED body (`res.Body` from spec.Resolve — the same text
the prompt template receives). Order of first occurrence; dedup by RESOLVED document id (two URL
forms of one doc collapse); cap `maxArtifactRefs = 10` (const, not config) — refs past the cap get
manifest lines "skipped: over per-task artifact cap".

Why bare-URL matching, not an `artifact:` prefix line:
(a) descriptions reach the daemon in TWO shapes — raw markdown on daemon-created child cards, and
    TipTap HTML (`<p>…<a href="URL">text</a></p>`) on operator-edited cards; internal/vikunja
    passes Description verbatim (board.go), nothing normalizes HTML — a line-anchored convention
    breaks under HTML rewrapping, host+path substring matching survives both;
(b) zero ceremony: paste a link into the card and it just works;
(c) false positives are benign — a linked Yonote doc IS relevant context by definition.
`/collection/...` and `/share/...` URLs deliberately NOT matched in v1. Resolution: pass `<seg>`
verbatim to documents.info (accepts uuid | urlId | slug-urlId — live-verified) → canonical uuid,
title, archivedAt.

## Claim flow (internal/reconcile claim(), after renderPrompt succeeds, before runner.Start)

    refs := yonote.ParseDocRefs(cfg.Yonote.BaseURL, res.Body)     // nil client or 0 refs → unchanged behavior
    ctx2 := context.WithTimeout(ctx, cfg.Yonote.ClaimBudget)      // one budget for ALL refs; reconcile loop is single-goroutine (PublishTimeout precedent)
    serially per ref:
      doc, err := DocumentInfo(ctx2, ref)          // err (404 deleted, 401, timeout…) → unavailable(reason), continue
      md, err  := ExportMarkdown(ctx2, doc.ID)     // MUST use doc.ID (uuid) — urlId 400s
      if err (incl. whiteboard 500) → unavailable(reason)
      if md == ""       → md = doc.Text            // API-created never-edited docs keep markdown in .text; database docs are "" both ways
      if md still ""    → unavailable("document exported empty")
      marker "(archived)" when doc.ArchivedAt != nil — still materialized (archived docs stay readable)
      Artifact{FileName: fmt.Sprintf("%02d-%s.md", n, slug(doc.Title)), Content: md,
               Title: doc.Title, SourceURL: cfg.Yonote.BaseURL + doc.URL}
    budget exhausted → remaining refs unavailable("artifact budget exhausted")

slug(): lowercase; non-[a-z0-9] runs → "-"; trim "-"; cap 60 chars; empty → doc.URLID. The NN-
ordinal prefix makes collisions impossible. Cyrillic titles will slug to "" often → URLID fallback
matters.

FAILURE SEMANTICS (spec-style): NOTHING in materialization ever fails or bounces the claim. A dead
/ archived / empty / oversized-budget reference degrades to a manifest warning line + a claim-
comment count + a warn log. Rationale: the doc is context, not a precondition; the operator sees
the warning immediately (prompt + card comment) and can fix the link and re-run. No triage bounce
(spec is not malformed), no failed state (nothing ran).

## Prompt manifest

Reconciler APPENDS to the rendered prompt (role templates untouched; keeps SPEC §12 rendering
contract intact):

    ## Reference documents (.task/artifacts/)
    Exported from Yonote at claim time; read them before starting; treat as read-only input.
    1. "<Title>" — .task/artifacts/01-<slug>.md (source: <abs url>)
    2. "<Title>" (archived) — .task/artifacts/02-<slug>.md (source: <abs url>)
    3. "<Title or ref>" — UNAVAILABLE (<reason>) (source: <abs url>)

## Ports + runner

- ports.StartSpec gains `Artifacts []Artifact`; `type Artifact struct{ FileName, Content, Title, SourceURL string }`.
- runner prepareTaskDir: ALWAYS `os.RemoveAll(.task/artifacts)` first (attempt-scoped channel —
  same rationale as clearing summary/tasks/question: attempt N-1 exports must not leak into
  attempt N). Then when len(Artifacts)>0: MkdirAll + writeFileAtomic each. Guard: reject FileName
  containing "/" or ".." (defense in depth; daemon generates them).
- RE-CLAIM SEMANTICS (DECISION): every attempt RE-EXPORTS fresh content. Freshness wins over
  snapshot stability because the whole point is "the current spec", specs get edited between
  attempts, and each finished attempt's snapshot is already preserved by the Done-archive tar.gz.
  A doc that died between attempts becomes an UNAVAILABLE manifest line (stale file removed by the
  RemoveAll), so the agent never reads outdated content silently.

## Observability

- Claim comment (existing "attempt N started · …" line) gains, only when refs were found:
  `· artifacts: N exported[, M unavailable]`.
- appendEvent "artifacts" {"exported": N, "unavailable": M} (deduped like existing events).

## Interface seam

reconcile depends on a narrow local interface (fake-friendly, matches existing port style):

    type yonoteExporter interface {
        DocumentInfo(ctx context.Context, id string) (*yonote.Document, error)
        ExportMarkdown(ctx context.Context, uuid string) (string, error)
    }

nil = feature off. *yonote.Client satisfies it.

## Tests

- config: block absent (inert) / present-partial (errors join) / bad URL / ${VAR} unset problem /
  budget default + non-positive rejection (mirror telegram/ntfy config tests).
- reconcile claim with fake exporter: 2-ref happy path (manifest text, StartSpec.Artifacts,
  comment suffix, event payload); 404 ref → UNAVAILABLE + claim proceeds; markdown "" → Text
  fallback; both empty → unavailable; budget timeout → remaining skipped; dedup two URL forms of
  one doc; TipTap-HTML description with <a href=...>; cap at 10; archived marker; nil exporter →
  byte-identical prompt to today.
- runner: artifacts written under .task/artifacts/; stale dir removed when Artifacts empty;
  traversal FileName rejected.

wave 2.5 — implement after feat/wave2-archive-links merges. Depends on the internal/yonote client
bead.

Code-recon evidence: (1) descriptions reach the daemon VERBATIM — internal/vikunja/board.go:110 copies wire Description straight into ports.BoardTask; there is NO html→markdown normalization on read (markdownToHTML in internal/vikunja/markdown.go is write-side, comments only) — so operator-edited cards arrive as TipTap HTML while daemon-created child cards (reconcile.go childDescription) are raw markdown: the URL scanner must handle both, which is why the convention is host+path substring matching, not an 'artifact:' line. (2) Hook point: internal/reconcile/reconcile.go claim(), after renderPrompt success (~line 362-404) and before runner.Start; prompt is plain string concatenation — role templates (SPEC §12) stay untouched. (3) File writing: internal/runner/runner.go prepareTaskDir (~591-633) already clears attempt-scoped channels (summary/tasks/question) — artifacts dir clearing joins that list; writeFileAtomic + excludeTaskDir + Done-archive tar.gz already cover durability/git-exclusion/archival (SPEC §9). (4) API evidence for the fallback chain and failure modes lives in ah-gxa notes: /markdown is uuid-only, returns '' for API-created-never-edited drafts and database docs, 500s for whiteboards, and .text is plaintext after editor edits — hence markdown → .text → UNAVAILABLE. (5) claim runs on the single reconcile goroutine — claim_budget bounds total materialization wall-clock (PublishTimeout precedent, config.go). (6) documents.info of an ARCHIVED doc was NOT live-verifiable (workspace has no archived docs); Outline heritage says it returns the doc with archivedAt set — treated as exportable + '(archived)' marker; implementer verifies by archiving a scratch doc in the UI once. Nested docs: no doc with childrenCount>0 exists in the workspace; /markdown has no children param (single-doc export is spec-consistent) — v1 semantics = SINGLE doc per reference, children never walked (documents.list {parentDocumentId} exists if a future version wants a tree).