Align docs domain frontmatter with Google's Open Knowledge Format

[rgdevme]

Summary

• Replace the user-overridable docs.metadata config with a fixed six-field OKF-aligned frontmatter schema (type/title/description/resource/tags/timestamp). type/title/description/timestamp are required and non-empty; resource/tags must be present but may be empty. Drops read_when/agent_cant.
• Reserve log.md alongside index.md (excluded from the scan and the watcher) so an agent can maintain an OKF-style prose change log without triggering recompilation.
• Move the authoring conventions out of the dead doc-rules.md template (confirmed unreferenced by any code path) into two discoverable skills: doc-authoring and doc-authoring-with-logs (adds prose log.md maintenance — instruction-based, since OKF log entries are prose, not generated output).
• Remove the docs domain's entire templates/ directory (all three files and their slot-injection markers were dead code) and update copy-templates.mjs + schema.json accordingly.
• Migrate the repo's own .docs/ to the new frontmatter shape.

Test plan

• pnpm lint && pnpm typecheck && pnpm test && pnpm build all pass (241 tests)
• Manually verified against the built dist: the migrated .docs/plans/*.md validate against the new schema, and both new skills are discovered via findSkillsInRepo
• Added a regression test for YAML auto-parsing an unquoted ISO timestamp into a Date (caught during manual verification — timestamp now accepts string | Date)

[qodo-code-review]

PR Summary by Qodo

Align docs frontmatter schema with Open Knowledge Format (OKF)

✨ Enhancement 🧪 Tests 📝 Documentation ⚙️ Configuration changes 🕐 40+ Minutes

AI Description

• Replace configurable docs metadata with a fixed OKF-aligned six-field frontmatter schema.
• Exclude reserved index.md and new log.md from docs scanning and watcher triggers.
• Remove dead docs templates and add discoverable doc-authoring skills and regression tests.

Diagram

graph TD
  A["Docs domain"] --> B["compileDocsIndex"] --> C[(".docs bundle")]
  B --> D["docFrontmatterSchema"]
  B --> E["index.md output"]
  A --> F["watchIgnore"] --> G["ignore: index.md, log.md"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep configurable metadata map (defaults + overrides)

• ➕ More flexible for non-OKF adopters
• ➕ Avoids breaking config consumers that relied on custom metadata keys
• ➖ Drifts from OKF interoperability goals
• ➖ Complicates validation and user support (schema becomes ambiguous)

2. Make frontmatter validation strict (fail compile/build)

• ➕ Prevents incomplete metadata from silently shipping
• ➕ Forces consistent indexing and downstream tooling expectations
• ➖ Higher adoption friction during migration
• ➖ Harder to handle legacy docs bundles and partial authoring workflows

3. Use JSON Schema (schema.json) as the single source of truth for frontmatter

• ➕ Avoids duplication between Zod and JSON schema descriptions
• ➕ Potentially enables tooling reuse across CLI/editor integrations
• ➖ Requires a JSONSchema→runtime validation bridge (extra dependency/complexity)
• ➖ Zod-based descriptions are already used for user-facing hints/warnings

Recommendation: The chosen approach (fixed OKF schema + warning-on-incomplete) is the best tradeoff for interoperability and incremental adoption. Keeping validation non-fatal preserves current behavior (index still generated) while providing clear, schema-derived guidance, and reserving log.md is a pragmatic way to support OKF-style prose logs without rebuild churn.

Files changed (14) +365 / -78

Enhancement (4) +64 / -36

index.tsExport docFrontmatterSchema from core index +1/-0

Export docFrontmatterSchema from core index

• Re-exports the new 'docFrontmatterSchema' so domains/tests can import it from the public core entrypoint.

src/core/index.ts

schema.tsDefine fixed OKF docFrontmatterSchema and drop docs metadata overrides +29/-5

Define fixed OKF docFrontmatterSchema and drop docs metadata overrides

• Removes the prior 'metadataSchema' and makes docs config only specify 'root'. Adds 'docFrontmatterSchema' (passthrough) with required non-empty fields and 'timestamp' accepting 'string | Date' to handle YAML parsing.

src/core/schema.ts

compile.tsValidate docs against docFrontmatterSchema and reserve log.md +29/-28

Validate docs against docFrontmatterSchema and reserve log.md

• Replaces the configurable metadata-key checking with 'docFrontmatterSchema' validation, tracks incomplete docs via an 'incomplete' list, and improves warnings by printing the schema-derived metadata shape. Excludes both 'index.md' and reserved 'log.md' from scanning.

src/domains/docs/compile.ts

index.tsIgnore log.md in docs watcher triggers +5/-3

Ignore log.md in docs watcher triggers

• Extends watcher ignore rules to exclude both generated 'index.md' and reserved 'log.md', preventing agent-maintained logs from retriggering compilation.

src/domains/docs/index.ts

Refactor (1) +0 / -2

public.tsRemove DocsConfig.metadata from public types +0/-2

Remove DocsConfig.metadata from public types

• Updates the exported 'DocsConfig' interface to eliminate the 'metadata' field now that frontmatter shape is fixed.

src/core/types/public.ts

Tests (2) +124 / -26

schema.test.tsAdd schema tests for docFrontmatterSchema and docsConfigSchema change +39/-2

Add schema tests for docFrontmatterSchema and docsConfigSchema change

• Updates the docs config test to assert 'metadata' is no longer present and adds coverage for required OKF fields, passthrough behavior, and empty 'resource'/'tags' acceptance.

test/core/schema.test.ts

compile.test.tsUpdate docs compile tests for OKF schema, log.md exclusion, and YAML Date parsing +85/-24

Update docs compile tests for OKF schema, log.md exclusion, and YAML Date parsing

• Refactors test doc generation to use gray-matter serialization, removes tests for 'effectiveMetadata', and adds cases for schema completeness, reserved file exclusions, warning message formatting, and unquoted ISO timestamps parsed as 'Date'.

test/docs/compile.test.ts

Documentation (5) +175 / -7

index.mdTighten docs index links and remove duplicate plan entry +1/-2

Tighten docs index links and remove duplicate plan entry

• Adjusts the generated docs index content to remove an extra list entry and normalize the PRD link label.

.docs/index.md

prd.mdMigrate PRD frontmatter to OKF six-field schema +5/-3

Migrate PRD frontmatter to OKF six-field schema

• Replaces legacy frontmatter fields ('read_when', 'agent_cant') with OKF-aligned keys ('type', 'resource', 'tags', 'timestamp') and ensures required fields are present.

.docs/plans/prd.md

refactor-implementation-plan.mdMigrate implementation plan frontmatter to OKF schema +4/-2

Migrate implementation plan frontmatter to OKF schema

• Adds 'type', 'resource', 'tags', and 'timestamp' fields and removes deprecated 'read_when'/'agent_cant' metadata.

.docs/plans/refactor-implementation-plan.md

SKILL.mdAdd doc-authoring skill including prose log.md maintenance +94/-0

Add doc-authoring skill including prose log.md maintenance

• Introduces a discoverable skill describing OKF-aligned frontmatter requirements, writing/linking conventions, and explicit instructions for maintaining a reserved 'log.md'.

skills/doc-authoring-with-logs/SKILL.md

SKILL.mdAdd doc-authoring skill for OKF-aligned docs bundles +71/-0

Add doc-authoring skill for OKF-aligned docs bundles

• Adds a discoverable skill defining the fixed six-field OKF frontmatter schema and authoring conventions for docs under the configured docs root.

skills/doc-authoring/SKILL.md

Other (2) +2 / -7

schema.jsonRemove configurable docs.metadata and document fixed frontmatter shape +1/-6

Remove configurable docs.metadata and document fixed frontmatter shape

• Updates the docs domain config schema to drop the 'metadata' override map and clarifies that the frontmatter schema is fixed to OKF fields.

schema.json

copy-templates.mjsStop copying docs templates into dist +1/-1

Stop copying docs templates into dist

• Removes 'src/domains/docs/templates' from the template copy list since docs templates are now deleted as dead code.

scripts/copy-templates.mjs

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (2) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 41 rules

1. JSDoc restates metadataShape() 📘 Rule violation ⚙ Maintainability

Description

The new JSDoc comment above metadataShape() mostly repeats what the function does rather than
explaining intent/rationale. This adds noise and can make it harder to spot comments that contain
important design context.

Code

src/domains/docs/compile.ts[67]

+/** The fixed frontmatter shape rendered as `key: <hint>` lines, in schema order. */

Relevance

⭐⭐⭐ High

Team previously accepted guidance to remove “comments restating what the code does” (PR12).

PR-#12

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Rule 704838 forbids comments that merely restate code behavior. The JSDoc `The fixed frontmatter
shape rendered as ... lines describes the immediate output of metadataShape()` without providing
rationale beyond what the implementation already shows.

Rule 704838: Comments must describe intent or rationale, not restate code behavior
src/domains/docs/compile.ts[67-72]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A newly added comment restates the immediate behavior of `metadataShape()` instead of documenting intent/rationale.

## Issue Context
Compliance requires comments to add intent/constraints/trade-offs, not narrate code. Either remove the comment or rewrite it to capture *why* schema order / this formatting is required (e.g., determinism for stable output, user-facing diagnostics format).

## Fix Focus Areas
- src/domains/docs/compile.ts[67-72]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. PRD missing required title 🐞 Bug ≡ Correctness

Description

.docs/plans/prd.md comments out the required title frontmatter field, so it will always fail
docFrontmatterSchema validation and be reported as incomplete. The generated docs index will also
fall back to the filename (prd) instead of the intended human title.

Code

.docs/plans/prd.md[R2-4]

+type: PRD
+# title: PRD — @luxia/agnos v0.1
description: Product requirements document for collapsing the 8-package monorepo into a single `@luxia/agnos` package and redesigning the domain model around config writers and a single config reader (agents).
-read_when: When planning or implementing the v0.1 refactor, choosing architectural patterns, or resolving design questions about the new domain model, packaging, or CLI shape.
-agent_cant: delete

Relevance

⭐⭐⭐ High

PR30 explicitly requires non-empty title; missing title breaks new schema and undermines the OKF
migration.

PR-#30

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

docFrontmatterSchema requires a non-empty title, but the PRD doc has title commented out, so
safeParse(data) will fail and the doc will be added to the incomplete list. When title is
missing, the index title falls back to the markdown filename (so it will show prd).

.docs/plans/prd.md[1-8]
src/core/schema.ts[93-118]
src/domains/docs/compile.ts[97-107]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The migrated `.docs/plans/prd.md` does not include a required, non-empty `title` in YAML frontmatter (it is commented out). This causes `compileDocsIndex()` to report the doc as incomplete on every run and to render an index entry title derived from the filename instead of the document’s intended title.

### Issue Context
- `docFrontmatterSchema` requires `title` to be present and non-empty.
- `compileDocsIndex()` warns on schema failures and uses a filename fallback when `title` is missing.

### Fix Focus Areas
- .docs/plans/prd.md[1-8]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. incomplete array not plural 📘 Rule violation ⚙ Maintainability

Description

The collection variable incomplete is an array but is not named with a plural noun, which reduces
clarity and violates the collection naming convention. This can lead to inconsistent naming patterns
across the codebase.

Code

src/domains/docs/compile.ts[95]

+  const incomplete: string[] = [];

Relevance

⭐ Low

Similar “pluralize collection variable names” suggestion was rejected in PR17, indicating
non-enforcement.

PR-#17

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Rule 704868 requires collection variables (arrays/lists) to be named with plural nouns. The code
declares const incomplete: string[] = [];, which is a collection but not a plural-noun identifier.

Rule 704868: Collection variables must be named with plural nouns
src/domains/docs/compile.ts[95-100]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A collection variable is named `incomplete`, but collections must be named with plural nouns.

## Issue Context
In `compileDocsIndex`, `incomplete` is a `string[]` (a collection) that stores multiple relative paths. Rename it to a plural-noun name (e.g., `incompleteFiles` or `incompleteDocs`) and update all references.

## Fix Focus Areas
- src/domains/docs/compile.ts[95-142]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[qodo-code-review]

2. Jsdoc restates metadatashape() 📘 Rule violation ⚙ Maintainability

The new JSDoc comment above metadataShape() mostly repeats what the function does rather than
explaining intent/rationale. This adds noise and can make it harder to spot comments that contain
important design context.

Agent Prompt

## Issue description
A newly added comment restates the immediate behavior of `metadataShape()` instead of documenting intent/rationale.

## Issue Context
Compliance requires comments to add intent/constraints/trade-offs, not narrate code. Either remove the comment or rewrite it to capture *why* schema order / this formatting is required (e.g., determinism for stable output, user-facing diagnostics format).

## Fix Focus Areas
- src/domains/docs/compile.ts[67-72]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-code-review]

3. Prd missing required title 🐞 Bug ≡ Correctness

.docs/plans/prd.md comments out the required title frontmatter field, so it will always fail
docFrontmatterSchema validation and be reported as incomplete. The generated docs index will also
fall back to the filename (prd) instead of the intended human title.

Agent Prompt

### Issue description
The migrated `.docs/plans/prd.md` does not include a required, non-empty `title` in YAML frontmatter (it is commented out). This causes `compileDocsIndex()` to report the doc as incomplete on every run and to render an index entry title derived from the filename instead of the document’s intended title.

### Issue Context
- `docFrontmatterSchema` requires `title` to be present and non-empty.
- `compileDocsIndex()` warns on schema failures and uses a filename fallback when `title` is missing.

### Fix Focus Areas
- .docs/plans/prd.md[1-8]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools