PRD: Semantic member hint round trip for orbit content

[zack-nova]

Problem Statement

Orbit authors can apply temporary content hints into authored Orbit member truth, but they do not have a reverse command that renders authored member configuration back into editable document and directory markers. This makes member truth hard to inspect and edit close to the maintained content it describes. The current hint model is also intentionally narrow: one hint describes the file or directory where it appears, duplicate member names conflict, and hint fields cannot express complex include/exclude paths. That model is not enough for a semantic round trip between OrbitSpec member truth and visible content hints.

The requested capability is intentionally not mature enough for implementation yet. The desired direction is clear enough to preserve as a PRD, but it needs more examples and design confirmation before it can become a Dev Brief.

Solution

Introduce Member Hint Rendering under the public command surface hyard orbit content render [package] as the authoring-side reverse of hyard orbit content apply [package]. The command renders authored Orbit member truth into Member Hint Frontmatter and Directory Member Marker hints for Source Revisions and Orbit Template Revisions.

The target product behavior is semantic Member Hint Round Trip: OrbitSpec -> hints -> OrbitSpec should preserve effective member semantics, including ordinary content roles, lane values supported by the hint schema, include paths, and exclude paths. It does not promise hints -> OrbitSpec -> hints will preserve the user's original marker layout.

To support semantic round trip, the hint model would allow same-name hints to aggregate into one Orbit member when non-path fields agree. It would also allow orbit_member.paths.include and orbit_member.paths.exclude selectors that are relative to the hint location. Rendering would place simple file includes in Markdown frontmatter, directory-wide includes in a directory marker, and directory selector includes in the longest stable directory marker with relative paths.

User Stories

1. As an Orbit author, I want to render authored Orbit member truth into visible content hints, so that I can review member configuration next to the maintained content it describes.
2. As an Orbit author, I want hyard orbit content render [package], so that the command is clearly the reverse of hyard orbit content apply [package] and not confused with root guidance rendering.
3. As an Orbit author, I want Markdown files to receive Member Hint Frontmatter when they represent file-level members, so that file membership can be edited in place.
4. As an Orbit author, I want directories to receive .orbit-member.yaml Directory Member Markers when they represent directory members, so that directory membership can be edited without modifying every file inside the directory.
5. As an Orbit author, I want a member with docs/**/*.md to render as a directory marker with relative path selectors, so that broad directory patterns remain compact and editable.
6. As an Orbit author, I want include and exclude selectors in hints to be relative to the hint location, so that markers remain anchored to nearby content instead of becoming detached repository-wide path declarations.
7. As an Orbit author, I want multiple same-name hints to aggregate into one Orbit member, so that one logical member can be represented by several marker locations when no single stable directory marker represents every include path.
8. As an Orbit author, I want same-name hints with conflicting role, lane, or description values to fail closed, so that accidental member merges do not silently corrupt authored truth.
9. As an Orbit author, I want render to preserve unrelated Markdown metadata, so that normal document frontmatter is not damaged by Harness Yard hints.
10. As an Orbit author, I want apply to remove only the orbit_member mapping from Markdown frontmatter, so that ordinary metadata remains intact after hints are consumed.
11. As an Orbit author, I want apply to delete consumed directory marker files, so that temporary authoring scaffolds do not become a second source of truth.
12. As an Orbit author, I want render to report equivalent existing hints as unchanged, so that repeated runs are predictable.
13. As an Orbit author, I want render to fail closed on non-equivalent existing hints by default, so that in-progress marker edits are not overwritten silently.
14. As an Orbit author, I want --force to explicitly overwrite non-equivalent hints from authored OrbitSpec truth, so that I can discard marker edits deliberately.
15. As an Orbit author, I want --check to preview render changes, so that I can inspect creates, updates, unchanged hints, skipped members, and conflicts before writing files.
16. As an Orbit author, I want missing target files or directories to be diagnosed rather than created by default, so that render does not invent maintained content accidentally.
17. As an Orbit author, I want an explicit missing-content option only if the design confirms it, so that creating placeholder Markdown or marker sidecars remains deliberate.
18. As an Orbit author, I want render -> apply to preserve effective Orbit member semantics, so that I can move between OrbitSpec truth and visible hints without losing member configuration.
19. As an Orbit author, I do not need apply -> render to preserve the exact old marker layout, so that implementation can choose a canonical marker placement.
20. As a maintainer, I want the hint parser to reject absolute paths, parent traversal, empty includes, and control-plane paths, so that relative hint selectors cannot escape safe content boundaries.
21. As a maintainer, I want meta-role members to remain out of the content hint render/apply flow, so that content hints cannot declare control-plane truth.
22. As a maintainer, I want scope overrides to remain out of hint schema, so that temporary content hints do not carry durable behavior policy.
23. As a maintainer, I want future lane support to extend hint schema deliberately, so that non-bootstrap lanes do not become accidental free-form metadata.
24. As a maintainer, I want runtime repositories excluded from v1 render/apply support, so that installed Harness Runtime package truth is not treated as the primary content hint authoring surface.
25. As a CLI user, I want JSON output for render checks and writes, so that automation can inspect what happened without parsing text output.
26. As a tester, I want unit tests for path normalization and aggregation, so that semantic round trip does not depend on CLI integration tests alone.
27. As a tester, I want integration tests for render/apply round trips, so that the public command behavior is covered end to end.
28. As a documentation reader, I want user conventions to explain the difference between root guidance markers and member hints, so that marker terminology stays unambiguous.
29. As a future implementer, I want this PRD kept in state:needs-info, so that the current immature design does not trigger implementation before examples and edge cases are validated.

Implementation Decisions

• Use the public command surface hyard orbit content render [package] for Member Hint Rendering.
• Treat the command as the reverse authoring action for hyard orbit content apply [package], not as part of root guidance rendering.
• Support Source Revisions and Orbit Template Revisions in the first version; do not make Harness Runtime repositories the primary content hint authoring surface.
• Preserve OrbitSpec as canonical authored truth. Member hints remain temporary authoring scaffolds and are consumed by apply.
• Target semantic Member Hint Round Trip for OrbitSpec -> hints -> OrbitSpec; do not preserve the exact user's marker layout after hints -> OrbitSpec -> hints.
• Extend the member hint schema with relative paths.include and paths.exclude selectors under orbit_member.
• Interpret explicit hint paths relative to the hint location. Markdown hint selectors are relative to the Markdown file's directory. Directory marker selectors are relative to the marker directory.
• Allow multiple same-name hints to aggregate into one Orbit member when their non-path fields agree.
• Fail closed when same-name hints disagree on non-path fields such as role, lane, or description.
• Keep role: meta outside content hint rendering and application.
• Keep member scope overrides outside content hint schema.
• Preserve the existing behavior that applying hints consumes them after writing Orbit member truth.
• Preserve unrelated Markdown metadata during render and apply.
• Render simple file includes into Markdown Member Hint Frontmatter.
• Render directory-wide includes into that directory's Directory Member Marker.
• Render directory selector includes such as docs/**/*.md into the longest stable directory marker with relative paths.
• Split one Orbit member across multiple same-name hints when no single stable marker location can represent all include paths.
• Default render behavior should fail closed on non-equivalent existing hints and require an explicit overwrite option to replace them from OrbitSpec truth.
• Provide check/preview output for render so users can inspect writes and conflicts before mutation.
• The likely deep modules are a relative hint path schema/parser, a same-name aggregation and validation planner, a render placement planner, a hint writer that preserves Markdown metadata, and CLI adapters that keep command files thin.

Testing Decisions

• Good tests should prove semantic round trip rather than incidental byte-for-byte marker layout preservation.
• Unit-test relative path normalization for Markdown hints and directory markers, including rejection of absolute paths, parent traversal, empty include sets, and control-plane paths.
• Unit-test same-name aggregation, including successful include/exclude merge and failure on inconsistent role, lane, or description.
• Unit-test render placement planning for single Markdown files, directory-wide includes, directory selector includes, exclude selectors, and members that must split across multiple marker locations.
• Unit-test Markdown frontmatter writes so ordinary document metadata is preserved and only the nested orbit_member mapping is added or replaced.
• Unit-test apply consumption so Markdown metadata remains and directory marker files are deleted after successful aggregation.
• Add CLI integration tests for hyard orbit content render [package] --check, normal render, conflict handling, explicit overwrite, and JSON output.
• Add round-trip integration tests that render from OrbitSpec, apply the generated hints, and compare the resulting OrbitSpec semantics with the original.
• Add tests showing that runtime repositories are not supported by v1 render/apply content hint authoring.
• Add documentation tests or release-surface checks if the public command help or user convention docs change.
• Normal implementation validation should run mise run fix and mise run ci; release-surface validation should run when public command/help/install surfaces change.

Out of Scope

• Implementing this feature immediately from the current discussion.
• Creating an ADR before the requirement is mature.
• Preserving exact marker layout across hints -> OrbitSpec -> hints.
• Treating hints as canonical authored truth or as a long-lived source beside OrbitSpec.
• Allowing content hints to express meta role members.
• Allowing content hints to express member scope overrides.
• Supporting Harness Runtime repositories as the v1 primary content hint authoring surface.
• Changing root guidance marker syntax or root guidance render/save/sync behavior.
• Automatically creating missing maintained content files unless a future design explicitly approves that behavior.
• Publishing child implementation issues before the missing information is resolved.

Further Notes

This PRD captures an immature design direction from a grill-with-docs discussion. It intentionally remains in state:needs-info. The current design memory has been updated with provisional domain language for Member Hint Rendering and Member Hint Round Trip, but the maintainer explicitly chose not to create an ADR yet.

Open information needed before this can become ready for development includes concrete examples for complex include/exclude members, final confirmation of the relative paths schema, final policy for missing target files/directories, and whether the feature should be split before implementation.

Blocked by

None - child issues not published yet.

[zack-nova]

Triage Notes

State: state:needs-info.

Reason: this PRD preserves a promising but immature design direction. It should not enter ready-for-dev until a maintainer confirms concrete examples for complex include/exclude members, the final relative orbit_member.paths schema, the missing target file/directory policy, and whether this should be split into child implementation issues.

The requested user-facing label was "need info"; the repository tracker contract represents that state as state:needs-info.