[repository-quality] Repository Quality Improvement Report - Frontmatter Reference Coverage Gap

[github-actions[bot]]

🎯 Repository Quality Improvement Report - Frontmatter Reference Coverage Gap

Analysis Date: 2026-09-30
Focus Area: Frontmatter Reference Coverage Gap (schema vs. frontmatter.md)
Strategy Type: Custom
Custom Area: Yes — the main docs entry point for frontmatter is hand-maintained and can drift from main_workflow_schema.json; no prior run audited schema-to-docs parity.

Executive Summary

pkg/parser/schemas/main_workflow_schema.json defines 68 top-level frontmatter properties. Every one appears somewhere in the docs (mostly the auto-generated frontmatter-full.md). However, 11 are never mentioned in the hand-written reference/frontmatter.md, which is the primary "all options" page: inlined-imports, models, experiments, enclaves, sandbox, max-tool-denials, mcp-servers, lsp, secret-masking, graders, evals.

Two are especially thinly documented. lsp is described only in the glossary and frontmatter-full.md. secret-masking is described only in architecture.mdx, imports.md and the hash spec. Users following the summary page never discover these fields, and nothing guards against future drift.

Full Analysis Report

Focus Area: Frontmatter Reference Coverage

Current State Assessment

Metrics Collected:

Metric	Value	Status
Top-level schema properties	68	i️
Mentioned anywhere in docs	68 (100%)	✅
Mentioned in reference/frontmatter.md	57 (84%)	⚠️
Missing from frontmatter.md	11	❌
Fields with no dedicated reference page (lsp, secret-masking)	2	❌
Automated schema↔docs parity check	none found	❌

Findings

Strengths

• frontmatter-full.md covers all fields.
• Dedicated pages already exist for sandbox, mcp-servers (guides/mcps.md), experiments, enclaves, graders, and inlined-imports (imports.md § Self-Contained Lock Files).

Areas for Improvement

• ⚠️ Nine fields have a dedicated page but no pointer from the summary page (frontmatter.md, 761 lines).
• ❌ lsp is documented only in glossary.md:958.
• ❌ secret-masking is documented only in architecture.mdx:638.
• ⚠️ max-tool-denials is documented in engines.md but is absent from the summary page's guardrail cluster (max-turns, max-ai-credits, ...).
• ⚠️ No CI test keeps the summary page in sync with the schema.

---

🤖 Tasks for Copilot Agent

NOTE TO PLANNER AGENT: Split the following tasks into individual work items.

Improvement Tasks

Task 1: Add missing summary sections to frontmatter.md

Priority: Medium
Estimated Effort: Small
Focus Area: Documentation

Description: Add short ### Title (field:) sections, each with a minimal YAML example and a link to the detailed page, for the 9 fields that already have detailed docs: inlined-imports, models, experiments, enclaves, sandbox, max-tool-denials, mcp-servers, graders, evals.

Acceptance Criteria:

• Each of the 9 fields has a section in frontmatter.md
• Each section links to its detailed page
• Section order and style match the existing sections

Code Region: docs/src/content/docs/reference/frontmatter.md

Follow the documentation skill. For each of inlined-imports, models, experiments, enclaves, sandbox, max-tool-denials, mcp-servers, graders and evals, add a concise section to docs/src/content/docs/reference/frontmatter.md. Use a schema-accurate example from pkg/parser/schemas/main_workflow_schema.json and link to the existing detailed page. Experimental fields must be marked experimental.

---

Task 2: Give lsp and secret-masking proper reference documentation

Priority: Medium
Estimated Effort: Medium
Focus Area: Documentation

Description: Add reference documentation for lsp: and secret-masking:, using the schema descriptions and the existing glossary and architecture text as sources. Add a summary section for each in frontmatter.md, and cross-link from the glossary and architecture pages.

Acceptance Criteria:

• A section or page covers each field, with examples that compile
• frontmatter.md links to both
• Examples are validated with gh aw compile

Code Region: docs/src/content/docs/reference/ (new or extended pages), glossary.md:958, introduction/architecture.mdx:638

Document the `lsp` and `secret-masking` frontmatter fields in docs/src/content/docs/reference/, consolidating what exists in glossary.md and architecture.mdx. Verify the examples compile and add cross-links. Use the documentation skill conventions.

---

Task 3: Add a schema-to-docs parity test

Priority: High
Estimated Effort: Medium
Focus Area: Testing / Documentation

Description: Add a Go test that loads the top-level properties of main_workflow_schema.json and asserts each appears as a backticked name: in frontmatter.md. Keep a small, justified allowlist for internal or deprecated fields. Run it in unit tests.

Acceptance Criteria:

• The test fails when a new schema property is undocumented
• The allowlist entries carry a justification comment
• The test passes after Tasks 1 and 2 land

Code Region: pkg/parser/ (new frontmatter_docs_parity_test.go), pkg/parser/schemas/main_workflow_schema.json

Create a Go test that reads pkg/parser/schemas/main_workflow_schema.json and docs/src/content/docs/reference/frontmatter.md and fails for any top-level property not documented in the latter. Use an allowlist with justification comments for deprecated or internal fields. Follow the repo's testing conventions and run `make fmt`.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-09-28	Skill Doc Drift (3rd audit)	Custom	Y	22 stale JS path refs
2026-09-29	Uncancellable Subprocess Execution	Custom	Y	exec.Command without context
2026-09-30	Frontmatter Reference Coverage Gap	Custom	Y	11 fields missing from summary page

---

🎯 Recommendations

Immediate Actions (This Week)

1. Add the schema↔docs parity test (Task 3) — Priority: High

Short-term Actions (This Month)

1. Fill in the missing summary sections (Tasks 1–2) — Priority: Medium

Long-term Actions (This Quarter)

1. Generate the summary page's field index from the schema — Priority: Low

---

📈 Success Metrics

• Schema fields covered in frontmatter.md: 57/68 → 68/68
• Automated parity guard: none → in CI

---

Next Steps

1. Review and prioritise the tasks above
2. Assign tasks to Copilot coding agent via planner agent
3. Track progress on improvement items
4. Re-evaluate this focus area in 4 weeks

---

Generated by Repository Quality Improvement Agent
Next analysis: 2026-10-01 — Focus area selected by diversity algorithm

Generated by ⚡ Repository Quality Improvement Agent · copilot · auto · 24.6 AIC · ⌖ 7.66 AIC · ⊞ 9.7K · ◷

• expires on Oct 1, 2026, 5:09 AM UTC-08:00

[github-actions[bot]]

This discussion has been marked as outdated by Repository Quality Improvement Agent.

A newer discussion is available at Discussion #64772.