T-A27K-field-reference-docs-with-evidence

State: planning/proposed · Impact: medium · Complexity: medium

Goal

A field’s info popover today says what the field does but never where that claim comes from, so a user setting allowed-tools for Codex has no way to check whether Codex honors it. This task gives every field a documentation entry with a per-harness support table and sourced links, reachable from the popover in one click — the ground truth the per-target warnings task links back to.

Today

Location	Role today
solutions/determined/experiences/agent-pants/app/utils/fieldSpec.ts#FIELD_SPECS	25 entries (id, key, label, help, kinds); no docId and no source citation
solutions/determined/experiences/agent-pants/app/utils/fieldSpec.ts#VAULT_ONLY_NOTE	One shared popover sentence for every ap- vault-only field; no per-field sourcing
packages/ts/ui/app/components/DFieldRow.vue	Popover renders help, storedAs and note; no link-out affordance
solutions/determined/experiences/agent-pants/app/plugins/register.ts	contributes.docs registers six manual chapters; none field-scoped
packages/ts/app-frame/app/components/ShellHelpButton.vue	doc="<module>/<id>" addressing already used four times in agent-pants pages (e.g. doc="agent-pants/getting-started")
solutions/determined/experiences/agent-pants/docs/frontmatter-reference.md	A coarse manual chapter walking Spec/Our/Everything-else field groups in prose; not per-field, and not linked from the popover
solutions/determined/experiences/agent-pants/app/components/SkillFieldsForm.vue	Reads every DFieldRow prop from fieldRowProps (s()); the one place that could wire a field’s docId into a concrete /help address

Proposed

Every FIELD_SPECS entry carries a docId. A new chapter set, solutions/determined/experiences/agent-pants/docs/fields/<key>.md, holds one file per field: what it does, its storedAs key, a per-harness support table drawn from T-HLEW-harness-capability-matrix (native | translated | ignored | rejected per RuntimeId), and the sources behind those cells with URLs and fetch dates. Each chapter registers through contributes.docs. DFieldRow gains a generic “Learn more” link affordance — a plain href, not an import of ShellHelpButton (packages/ts/ui does not depend on @sksizer/app-frame) — and SkillFieldsForm.vue computes the concrete /help?doc=agent-pants/field-<key> address from each field’s docId and passes it through. The allowed-tools chapter is the model entry: it is the field the user cited when asking for this, and its shape (what/stored-as/support-table/sources) is what every other chapter follows.

Approach

1. Add docId?: string to the FieldSpec interface in fieldSpec.ts; set it on all 25 entries (field-<key>, e.g. field-allowed-tools), matching the contributes.docs id each chapter registers under.
2. Design DFieldRow’s learn-more affordance as a plain prop (e.g. docHref?: string) rendering an anchor inside the existing popover, not a ShellHelpButton import — packages/ts/ui sits below @sksizer/app-frame in the layer stack and must not learn about /help. Open decision: whether the anchor also closes the popover on click, or leaves it open behind the modal reader.
3. In SkillFieldsForm.vue (or fieldRowProps), compute docHref from each field’s docId as /help?doc=agent-pants/${docId} and pass it into DFieldRow.
4. Write docs/fields/<key>.md for every FIELD_SPECS entry, starting with allowed-tools.md as the template: what the field does, Stored as the key, a support table with one row per RuntimeId from the capability matrix, and a Sources list (URL, fetched date) matching the matrix’s evidence records for that field’s cells.
5. Register all 25 chapters in register.ts’s contributes.docs, each a dynamic import (() => import('../../docs/fields/<key>.md?raw').then((m) => m.default)) so an unopened chapter costs nothing but its title, matching the existing six chapters’ pattern.
6. Verify every chapter’s support table matches the capability matrix for that field (spot-check in review; a full cross-check test is out of scope here) and that moon run product-agent-pants:check passes.

Areas

Area	Note
solutions/determined/experiences/agent-pants/app/utils/fieldSpec.ts	FieldSpec.docId; set on all 25 entries
solutions/determined/experiences/agent-pants/docs/fields/	One .md chapter per field, allowed-tools.md first as the template
solutions/determined/experiences/agent-pants/app/plugins/register.ts	25 new contributes.docs entries
packages/ts/ui/app/components/DFieldRow.vue	docHref prop; “Learn more” link in the popover
solutions/determined/experiences/agent-pants/app/components/SkillFieldsForm.vue	Compute docHref from each field’s docId

Acceptance criteria

• AC-1: Every entry in FIELD_SPECS carries a docId whose chapter exists under solutions/determined/experiences/agent-pants/docs/fields/*.md.
• AC-2: DFieldRow’s popover shows a “Learn more” link whenever a docHref is supplied, and the link opens /help?doc=agent-pants/field-<key>.
• AC-3: docs/fields/allowed-tools.md documents what the field does, its Stored as key, a support table with one row per RuntimeId, and a Sources list with URLs and fetch dates — the format every other chapter in the set follows.
• AC-4: Every chapter under docs/fields/*.md cites at least one URL with a fetch date.
• AC-5: The file count under docs/fields/*.md equals FIELD_SPECS.length (25 at the time of writing) — no field left undocumented, no orphaned chapter.
• AC-6: moon run product-agent-pants:check passes.

Out of scope

• Rewriting frontmatter-reference.md into per-field chapters — it stays the manual’s narrative walkthrough; the new chapters are the popover’s deep-link target, not its replacement.
• Modelling disallowed-tools as a new frontmatter field — the user cited it as the documentation format’s model entry, not as a field to add; FIELD_SPECS gains no new key in this task.
• Changing ShellHelpButton.vue, useDocs.ts, or the /help?doc=<module>/<id> addressing scheme — it already supports what this task needs.

Dependencies

• T-HLEW-harness-capability-matrix: the per-field support tables and evidence come from the matrix; this task cannot write a chapter’s support table before that matrix exists.

Discovery context

From the user’s Agent Manager planning request of 2026-09-07, which named disallowedTools as the model entry for what a field’s documentation should show. Grounded in the spec-adherence audit solutions/agent-pants/docs/vault/research/agent-skills-conformance.md (today’s Rust-only validation, no client-facing sourcing) and the harness survey solutions/agent-pants/docs/vault/reference/harness-comparison.md. Member of M-BMFD.

Depends on

T-HLEW-harness-capability-matrix

---

← Back to Tasks