Docs: spec.taskTemplate.metadata (labels/annotations) and spec.taskTemplate.upstreamRepo undocumented

[kelos-bot]

🤖 Kelos User Agent @gjkim42

Summary

Two `spec.taskTemplate` fields are fully implemented and in active use but completely absent from `docs/reference.md`:

1. `spec.taskTemplate.metadata` — adds custom labels and annotations to spawned Tasks, with Go template variable support
2. `spec.taskTemplate.upstreamRepo` — sets `KELOS_UPSTREAM_REPO` in agent containers for fork workflows

The first field appears in example 10 (`examples/10-taskspawner-github-webhook/taskspawner.yaml`, lines 115–124), so new users following that example can see it in action but have no reference to explain it.

What's missing

1. `spec.taskTemplate.metadata` — not in reference.md

`examples/10-taskspawner-github-webhook/taskspawner.yaml` uses it:

```yaml
metadata:
labels:
kelos.dev/trigger: "webhook"
kelos.dev/event: "{{.Event}}"
kelos.dev/action: "{{.Action}}"
annotations:
kelos.dev/github-url: "{{.URL}}"
kelos.dev/github-sender: "{{.Sender}}"
```

But `docs/reference.md` has no rows for:

• `spec.taskTemplate.metadata.labels` — map of label key → Go template value; merged into spawned Task labels; same template variables as `branch` and `promptTemplate`
• `spec.taskTemplate.metadata.annotations` — map of annotation key → Go template value

Key semantics new users need to know:

• Values support the same Go template variables as `branch` and `promptTemplate`
• The `kelos.dev/taskspawner` label is always set to the TaskSpawner name; any user value for that key is overridden
• Source annotations (e.g. `kelos.dev/source-kind`) are applied after rendering and override conflicting user values

2. `spec.taskTemplate.upstreamRepo` — not in reference.md

`self-development/kelos-pr-responder.yaml` references `KELOS_UPSTREAM_REPO` as an env var injected by this field, but neither the field name nor the env var are documented anywhere in user-facing docs.

Missing entry for:

• `spec.taskTemplate.upstreamRepo` — upstream repository (`owner/repo` format) injected as `KELOS_UPSTREAM_REPO` into agent containers; typically auto-derived from `githubIssues.repo` / `githubPullRequests.repo` but can be set explicitly for fork workflows

Suggested fix

Add the following rows to the `spec.taskTemplate` table in `docs/reference.md`:

Field	Description	Required
`spec.taskTemplate.metadata.labels`	Labels added to spawned Tasks; values support Go template variables (same as `branch`/`promptTemplate`); `kelos.dev/taskspawner` is always set and overrides user values	No
`spec.taskTemplate.metadata.annotations`	Annotations added to spawned Tasks; values support Go template variables; source annotations override conflicting user values	No
`spec.taskTemplate.upstreamRepo`	Upstream repository (`owner/repo`) injected as `KELOS_UPSTREAM_REPO` into the agent container; auto-derived from `githubIssues.repo`/`githubPullRequests.repo` when set, but can be overridden explicitly	No

[kelos-bot]

🤖 Kelos Task Status

Task kelos-triage-issues-df3122542053 has succeeded. ✅

[kelos-bot]

🤖 Kelos Agent @gjkim42

Kelos Triage Report

Kind: kind/docs
Priority: priority/important-longterm — Documentation gap for actively-used fields; valuable for new users following example 10, but not blocking adoption.
Actor: actor/kelos — Concrete docs-only change with clear scope and objectively verifiable acceptance (rows added to the spec.taskTemplate table in docs/reference.md).

Status: STILL VALID

Evidence:

• Both fields are defined in api/v1alpha1/taskspawner_types.go:
  • TaskTemplateMetadata struct at line 655–656; Metadata *TaskTemplateMetadata field at line 757–759
  • UpstreamRepo string field at line 761–767
• docs/reference.md spec.taskTemplate table (lines 214–223) has no rows for metadata.labels, metadata.annotations, or upstreamRepo. The only metadata hit in the file (line 69) is unrelated.
• No merged PRs reference Docs: spec.taskTemplate.metadata (labels/annotations) and spec.taskTemplate.upstreamRepo undocumented #1126 (gh pr list --state merged --search 1126 is empty); no commits on main mention 1126, upstreamRepo, or taskTemplate.metadata.
• Example 10 (examples/10-taskspawner-github-webhook/taskspawner.yaml) actively uses spec.taskTemplate.metadata, confirming the field is shipped and in production use without reference docs.

Duplicates found: None found. #1074 (agentConfigRefs undocumented) and #777 (Jira source type undocumented) follow the same pattern of missing reference docs but cover different fields — related, not duplicates.

Recommendation: KEEP OPEN — straightforward docs addition to docs/reference.md.