Design #53 — goal pages in the hub + goals move to issues

Requirement jwildfire/obot.roadmap#53 · companion requirement #71 (goals → issues) · from Ideas discussion #50 / #55 · Approved & implemented 2026-07-24

Plan reviewed and approved by @jwildfire 2026-07-24 (labels renamed to auto/draft; D1, D2, D4, D5 approved as proposed). Supersedes design #18 decision O2.

1. Summary

Standing goals move from files (obot.agent/goals/*.md) to hub goal issues, and the site gains one page per goal summarizing the goal and its member requirements, split by readiness. The design splits direction + membership (the goal issue — editable by @jwildfire with no PR ceremony) from the policy binding for autonomous selection (a thin registry that stays in obot.agent under the policy-file carve-out).

2. Representation: goal issues

One hub issue per goal, label goal, title prefix Goal:, kept open indefinitely — closing = retiring. GitHub-native custom issue types are an organization-plan feature, unavailable on this user-owned repo, so label + template is the formal mechanism (resolves the requirement's open question).
Requirements link to goals as native sub-issues (goal = parent), giving the goal issue GitHub's progress bar. Single-parent constraint: a requirement already parented by another requirement (phase children) inherits goal membership through its parent.

The goal issue body opens with a fenced YAML block — the machine-readable bits sub-issue links can't express:

```yaml
slug: charts                    # obot-auto --goal <slug>
anchors:                        # priority order
  - jwildfire/obot.roadmap#35
backlog:                        # hub issues or owner/repo issue backlogs
  - jwildfire/safety.viz
```

An issue form template, .github/ISSUE_TEMPLATE/goal.yml, scaffolds new goals (YAML block + Intent + Boundaries).

D1 (approved): goals are goal-labeled issues with sub-issue membership links; no custom issue type.

3. Readiness labels

auto — ready for autonomous implementation: the #18 implementation-ready criteria (design signed off, repo work scoped, inside the grant matrix).
draft — needs @jwildfire input or steering before implementation.
Sessions apply and refresh the labels during triage and wrapup, audited against the #18 criteria; @jwildfire overrides at will. The labels are display — --auto selection still evaluates the criteria directly, so a mislabeled issue cannot grant itself eligibility.

D3 (approved, amended): label names are auto / draft (@jwildfire 2026-07-24), not the proposed ready-for-auto / needs-steering.

4. What `--auto` reads

Concern	Lives in	Change path
Direction, boundaries, membership (anchors/backlog)	Hub goal issue	@jwildfire edits directly; agents propose via comment
Selectable set, active/paused, grant profile	`obot.agent/goals/registry.json`	PR through the policy-file carve-out — never merged unattended

scripts/obot-auto pre-flight resolves --goal <slug> against the registry (must exist with status: active) and reports the hub issue.
session-init --auto fetches the goal issue live: first YAML fence → ordered anchors + backlog; prose → binding boundaries. Selection order (anchors first, then backlog, never outside the grant matrix) is unchanged from #18.
A goal issue without a registry entry (today: #72 keynote, #73 autonomy) is display-only — visible on the site, never selected from. Adding one is a one-line registry PR.

D2 (approved): the thin policy registry stays in obot.agent inside the carve-out.

D4 (approved): autonomous sessions never edit goal issue bodies or sub-issue links — membership changes are proposed as comments. The rule is normative (session contract + wrapup audit); the mechanical backstops remain the grant matrix, merge policy, and registry carve-out.

D5 (approved): supersedes design #18 decision O2 ("goal definitions live in obot.agent, not the hub"). A supersession note is added to 18_design.html; nothing is deleted.

5. Site surfacing

scripts/lib/collect/goals.mjs (shared with the #57 roadmap page) reads open goal-labeled issues via GraphQL — issue + sub-issues + labels — replacing the file-based collector and the obot.agent checkout in deploy-site.yml.
scripts/build_goals.mjs renders /goals/ (index), /goals/{slug}.html per goal — direction prose, progress, members grouped Ready for auto / Needs steering / other / done, backlog feeds — and /goals/goals.json, the machine-readable summary the #57 homepage consumes.
Stable URLs: /goals/, /goals/charts.html, /goals/app.html, /goals/keynote.html, /goals/autonomy.html.

6. Migration & rollout (executed 2026-07-24)

Phase	What	Where	Gate
1 — hub content	Labels `auto`/`draft`; goal issues #78 (G1 charts) + #79 (G2 app) migrated verbatim from `charts.md`/`app.md`; pilot goals #72/#73 retrofitted with YAML blocks; 10 sub-issue links; `draft` applied to all 11 current members	obot.roadmap issues	@jwildfire reviews live goal issues
2 — machinery	`goals/registry.json`; `obot-auto` registry resolution; `session-init` goal-resolution + read-only rule; `charts.md`/`app.md` retired in-PR (no dark window: pre-merge sessions read files, post-merge read issues)	obot.agent#45 (draft)	@jwildfire review, `obot-merge` — carve-out, never unattended
3 — site	Collector rewrite, `build_goals.mjs`, goal template, deploy-workflow wiring, this design doc	obot.roadmap main	@jwildfire reviews deployed pages
4 — closeout	#18 O2 supersession note; #57 handoff (`goals.json` + URLs); #53/#71 updates	obot.roadmap	—

7. v2 amendment (2026-07-24, same day)

On reviewing the shipped goal issues, @jwildfire flagged the up-front YAML blocks and their staleness risk (a hand-maintained list duplicating the sub-issue links). Approved reshape:

Prose-only bodies. Goal issues carry no machine list. The only machine bit is a hidden  comment naming the site page.
Membership is generated, never maintained. Members = the sub-issue links, read live by --auto and the site collector; a newly linked sub-issue is automatically a member.
Priority is the selecting session's judgment at session start, guided by the goal's boundary prose and the #18 criteria — explicitly not sub-issue list order (@jwildfire: order-as-priority declined; priority labels are a future option if judgment underperforms). --increment still overrides.
The anchors/backlog distinction dissolves hub-side. Repo-level backlog feeds (e.g. jwildfire/safety.viz) move into goals/registry.json next to grant_profile — they are selection policy, and they can't be sub-issues anyway.
Lightweight tasks may live directly under goals without a requirement wrapper (@jwildfire, decided at v2 review): #66 → G1 charts, #70 → autonomy. Flagged, not linked: #44 (no clear goal), #27 (single-parent constraint — already under #24).
Freshness process: requirement #87 (weekly goal review, under goal #73) — a scheduled sweep proposing linkages, label refreshes, and orphan candidates as comments; @jwildfire applies. D4 (goal issues read-only for autonomous sessions) unchanged and now also protects membership/order.

8. Dependencies and open questions

#57 (homepage refactor): the staged roadmap page's Goals section and any homepage Goals surfacing consume collectGoals() / goals.json — goal pages provide the stable targets; homepage design stays #57's.
obot.agent#45 merge timing: until it merges, --auto still reads the goal files (which no longer exist on the branch — they remain on main); the site already reads issues. No coordination hazard: both sources currently describe the same two goals.
Open: whether #72/#73 get registry entries (making them --auto-selectable) — @jwildfire's call, one-line follow-ups.
Open: a "Goal" grouping field on the obot Roadmap project — deferred as optional polish.

This design document was drafted by Claude Code using Fable 5 and reviewed by @jwildfire.