v4.2 Codex quickstart: knowledge generator and schema migration defects

[markhazleton]

Summary

The v4.2 Codex quickstart exposed several defects while upgrading a repository and moving legacy .documentation/ content into the v4 knowledge layout.

Findings

1. Knowledge index generator resolves the wrong repository root when installed

   .devspark/scripts/python/build_knowledge_index.py used Path(__file__).resolve().parents[2], which resolved to .devspark/ instead of the repository root. Running the documented command created .devspark/.knowledge/ and reported .knowledge/entities as missing. The installed copy required parents[3] to locate the repository root.

2. Accidental .devspark/.knowledge/ output

   Because of the root-path defect, ontology reports were generated beneath .devspark/.knowledge/, contrary to the v4 rule that .knowledge/ is the sole durable knowledge root.

3. LinkedIn canonical schema resolver uses obsolete locations

   linkedin/lib/schema.ts searches only .documentation/specs/... and .archive/specs/... for the canonical carousel schema. After migrating current truth to .knowledge/ and work products to .devspark.work/, those paths are no longer valid. LinkedIn artifact generation can fail before generation with “Unable to locate canonical carousel schema.”

4. Knowledge scaffolding validation treats README files as decision records

   The generated .knowledge/governance/decisions/README.md was parsed as a decision and failed validation because it had no decision frontmatter/evidence. The scaffold README should either be excluded by the generator or placed outside the decision-record directory.

5. Quickstart command/shim naming is ambiguous

   The installation contained both prefixed and unprefixed stock command filenames, making command/shim counts and resolution difficult to validate reliably.

Expected behavior

• Installed utilities should resolve the repository root consistently.
• All generated ontology output should remain under the repository .knowledge/ root.
• v4.2 migration-aware commands should use .knowledge/ and .devspark.work/ paths, not legacy .documentation/ or .archive/ paths for current inputs.
• Scaffold README files should not be interpreted as decision records.
• Quickstart verification should report one canonical stock-command and shim mapping.

Environment

• DevSpark: v4.2.0
• Client: Codex quickstart
• OS: macOS
• Date: 2026-09-05