docs: document undocumented scripts, HVE Builder workflow, and planner state schemas

[jkim323]

Pull Request

Description

10 documentation-drift issues clustered onto ten files, so this change remediates all of them in one pass across four themes.

Script inventories. Three README files had fallen behind the scripts they describe. scripts/README.md documented 7 of the 20 scripts in scripts/evals/ and 4 of the 12 in scripts/security/; both sections are now complete, with a note naming the six eval scripts that have no package-script wrapper and are invoked directly. scripts/security/README.md gained full sections for the five scripts it never covered, each with features, parameters, and usage. scripts/linting/README.md gained Validate-AssetDocs.ps1, including its five-check table and the lint:asset-docs wrapper.

HVE Builder. docs/contributing/prompts.md described the pre-hve-builder workflow. It now carries a getting-started section covering the six modes and their write authority, the three compatibility-alias skills and what each routes to, the hve-builder-tester behavior-testing boundary, and where evidence lands. .github/instructions/hve-core/hve-builder.instructions.md gained a Skill-Forward Orchestrator Architecture section: the skill-first default, the responsibility split across skill, thin wrapper, path-scoped instructions, and background-only subagent, the user-invocable and disable-model-invocation controls, the rule that standalone-versus-parent branches live in the shared skill contract, and the six-property test for a dual-invocable agent. RPI is the worked example, and the change adds a matching quality criterion and stale-pattern rule.

Contributor guides. Three guides asserted "Attribution footer present" in their pre-submission checklists while their own body sections said source artifacts carry no footer, and the frontmatter validator treats the footer as an error on these file types. The checklists now say "absent." Two guides also claimed the attribution suffix is "added automatically at distribution"; that mechanism was removed and nothing in the build pipeline adds it, so the parenthetical is gone.

Planner schemas. docs/customization/build-system.md documented only frontmatter schemas. It now has a Planner State Schemas subsection mapping the four *-state.schema.json files to the .copilot-tracking/ paths they validate, stating that the schema wins when an inline agent example disagrees, and naming both enforcement paths: the json.schemas bindings in .vscode/settings.json and the two Pester suites.

Related Issue(s)

Fixes #2454
Fixes #2457
Fixes #1311
Fixes #2270
Fixes #2269
Fixes #1923
Fixes #2355
Fixes #2401
Fixes #2402
Fixes #2249

Type of Change

Select all that apply:

Code & Documentation:

• Bug fix (non-breaking change fixing an issue)
• New feature (non-breaking change adding functionality)
• Breaking change (fix or feature causing existing functionality to change)
• Documentation update

Infrastructure & Configuration:

• GitHub Actions workflow
• Linting configuration (markdown, PowerShell, etc.)
• Security configuration
• DevContainer configuration
• Dependency update

AI Artifacts:

• Reviewed contribution with hve-builder and addressed all actionable findings
• Copilot instructions (.github/instructions/*.instructions.md)
• Copilot prompt (.github/prompts/*.prompt.md)
• Copilot agent (.github/agents/*.agent.md)
• Copilot skill (.github/skills/*/SKILL.md)
• Copilot hook (.github/hooks/*/*.json)
• Eval spec added/updated for changed AI artifacts (evals/)

Note for AI Artifact Contributors:

• Agents: Research, indexing/referencing other project (using standard VS Code GitHub Copilot/MCP tools), planning, and general implementation agents likely already exist. Review .github/agents/ before creating new ones.
• Skills: Must include both bash and PowerShell scripts. See Skills.
• Model Versions: Only contributions targeting the latest Anthropic and OpenAI models will be accepted. Older model versions (e.g., GPT-3.5, Claude 3) will be rejected.
• See Agents Not Accepted and Model Version Requirements.

Security configuration is checked because scripts/security/README.md changed. No .ps1 file was modified; the change is documentation only.

Sample Prompts (for AI Artifact Contributions)

User Request:

Add a skill-forward architecture rule to the HVE Builder authoring standards.

Execution Flow:

The changed file is a path-scoped instruction file with applyTo: '**/*.prompt.md, **/*.agent.md, **/*.instructions.md, **/SKILL.md'. It is not invoked; it auto-applies whenever a matching artifact is created or edited. The new section participates in authoring the same way the existing sections do: it is consulted when deciding artifact type and responsibility split, and its quality criterion and stale-pattern entry are evaluated during review.

Output Artifacts:

No new files. The instruction file gains one section plus two list entries:

## Skill-Forward Orchestrator Architecture

Reusable behavior that must work both directly and under a parent belongs in a
user-invocable skill by default. Author the skill first, then add a wrapper only
when a user needs an entry point the skill alone does not provide.

Success Indicators:

Authoring a workflow that must run both standalone and under a parent produces one user-invocable skill plus a thin wrapper, rather than a single agent with two entry paths. Review of such an artifact flags duplicated standalone/orchestrated workflow logic against the new stale-pattern entry.

Note

This section was agent-populated and warrants human review.

For detailed contribution requirements, see:

• Common Standards: docs/contributing/ai-artifacts-common.md - Shared standards for XML blocks, markdown quality, RFC 2119, validation, and testing
• Agents: docs/contributing/custom-agents.md - Agent configurations with tools and behavior patterns
• Prompts: docs/contributing/prompts.md - Workflow-specific guidance with template variables
• Instructions: docs/contributing/instructions.md - Technology-specific standards with glob patterns
• Skills: docs/contributing/skills.md - Task execution utilities with cross-platform scripts

Testing

Content verification

Every factual assertion added by this change was checked against the tree rather than taken from the issue text:

• Script inventories were diffed programmatically against scripts/evals/, scripts/security/, and scripts/linting/. After the change, all three directories report zero undocumented scripts, and the Evals and Security sections of scripts/README.md report zero omissions.
• All 11 npm commands cited in new prose exist in package.json.
• All 11 file paths cited in new prose exist.
• The six modes documented for hve-builder match the argument-hint in its SKILL.md exactly.
• The security and SSSC state.json paths match their identity instruction files verbatim.
• The RPI example was confirmed against real frontmatter: rpi-agent.agent.md carries disable-model-invocation: true, and rpi-planner.agent.md and rpi-researcher.agent.md both carry user-invocable: false.
• Repository-wide searches confirm zero remaining occurrences of Attribution footer present and added automatically at distribution outside generated plugins/ output.
• The hve-builder.instructions.md change was checked for references to retired artifacts (prompt-builder.instructions.md, Code Review Full, dual-mode agents); none are present.

Staleness and conflict sweep

The branch base was rebased onto the then-current upstream/main and re-verified. The one intervening commit touches none of the ten changed files. No open pull request modifies these files.

Checklist

Required Checks

• Documentation is updated (if applicable)
• Files follow existing naming conventions
• Changes are backwards compatible (if applicable)
• Tests added for new functionality (if applicable) (N/A — documentation-only change adds no functionality)

AI Artifact Contributions

• Used hve-builder review mode to review contribution
• Addressed all actionable findings from the hve-builder review
• Verified contribution follows common standards and type-specific requirements

Required Local Checks

The following local-safe validation commands must pass before merging:

• Local validation aggregate: npm run validate:local
• Documentation validation (if docs changed): npm run validate:docs
• Spell checking: npm run spell-check
• Link validation: npm run lint:md-links

Security Considerations

• This PR does not contain any sensitive or NDA information
• Any new dependencies have been reviewed for security issues (N/A — no dependency changes)
• Security-related scripts follow the principle of least privilege (N/A — no scripts modified)

Additional Notes

GHCP Artifact Maturity

File	Type	Maturity	Notes
hve-core/hve-builder.instructions.md	Instructions	✅ stable	All builds

No maturity field is declared for this file in collections/hve-core.collection.yml or collections/hve-core-all.collection.yml, so it resolves to stable. No maturity acknowledgment is required.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.74%. Comparing base (2d1d25c) to head (ef2fb56).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2543      +/-   ##
==========================================
- Coverage   82.75%   82.74%   -0.01%     
==========================================
  Files         155      155              
  Lines       20960    20960              
  Branches       13       13              
==========================================
- Hits        17345    17344       -1     
- Misses       3613     3614       +1     
  Partials        2        2              

Flag	Coverage Δ
docusaurus	94.44% <ø> (ø)
pester	86.18% <ø> (-0.02%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Eval Execution

✅ Status: Passed

• Artifacts evaluated: 1
• Specs run: 1
• Assertions passed: 3
• Assertions failed (blocking): 0
• Assertions failed (advisory): 0
• Failed specs (merge-blocking): 0

Artifact	Kind	Status	Specs	Passed	Failed (blocking)	Failed (advisory)
hve-builder	instruction	✅ pass	1	3	0	0

Legend — ✅ clean · ⚠️ advisory failures only (non-blocking) · ⏭️ skipped · ❌ merge-blocking failure

Only Failed specs (merge-blocking) gates this PR. Advisory assertion failures are signal-quality checks captured during iteration; review them, but they do not block merge and may be acceptable.