AI-native workspace: full roadmap (Phases 1-4)

[lakpriya1s]

What & why

Implements the full 52-item roadmap in tasks.md for evolving devrig from an
"AI-ready multi-repo workspace" into an "AI-native development workspace
where agents can discover context, plan work, execute safely, verify
results, preserve knowledge, and improve future work." Delivered as four
phases (foundation → reliability → learning → intelligence/measurement),
one commit per phase.

Phase 1 — Foundation

• AGENTS.md: Commands table, Definition of Done pointer, concrete Semble
  retrieval policy, Context efficiency section.
• POLICY.md (new): Definition of Done, ADR requirement, verification
  evidence / confidence / source-citation formats, and (added in Phase 2)
  forbidden/approval-required actions, protected paths, risk levels, data
  handling, agent roles.
• Every knowledge/ doc now carries YAML frontmatter (status, authority,
  owners, authorship, …) instead of a plain blockquote — documented
  lifecycle states and authority ranking in knowledge/README.md.
• knowledge/index.md, generated by scripts/build-knowledge-index.mjs.
• /start-task gathers context (systems, ADRs, designs, likely files, risks,
  test plan) before any code changes; new /plan-task (written plan + human
  approval gate) and /verify-change (evidence per POLICY.md).

Phase 2 — Reliability

• .ai/{systems,commands,ownership,policies,risk-levels}.yaml mirror
  AGENTS.md/POLICY.md for tools/CI, validated against
  .ai/schemas/*.schema.json with a small dependency-free YAML/JSON-Schema
  reader (scripts/lib/).
• scripts/validate-knowledge.mjs (frontmatter completeness/enums,
  canonical-requires-human_reviewed, ADR id/filename consistency, broken
  links, generated-index freshness) and scripts/check-adr-requirement.mjs
  (protected-path change ⇒ ADR in the same diff), wired into
  .github/workflows/{validate,knowledge-check}.yml.
• /raise-pr's PR template now includes Systems affected, Testing (with
  /verify-change evidence), Risks, Documentation, ADR, Rollback.
• /plan-task reports Confidence/Assumptions/Unverified/Human-attention-required.

Phase 3 — Learning

• /start-task persists context to .ai/context/<TICKET>.json for reuse by
  /plan-task or a fresh session.
• knowledge/handoffs/ + template for interrupted-task working state,
  surfaced in the generated index.
• New /capture-learning: after a merge, asks the reflective questions (ADR?
  runbook? command/dependency change? recurring bug? stale docs?), writes
  confirmed items via /write-doc, cleans up handoff/context files.
• scripts/detect-doc-drift.mjs (non-blocking): systems.yaml/devrig.toml
  mismatches, dangling related/superseded_by ids, docs past their
  review_interval. New /check-knowledge-consistency for the semantic
  checks a script can't do (commands vs package.json, ownership vs
  CODEOWNERS, ADRs vs implementation, etc).

Phase 4 — Intelligence & measurement

• scripts/generate-architecture-views.mjs builds
  knowledge/generated/{system-map,ownership-map}.md from .ai/*.yaml
  (authority: generated).
• .ai/runs/<TICKET-ID>/ — a per-task observability trail written
  incrementally by /start-task → /plan-task → /verify-change →
  /raise-pr → /capture-learning.
• evals/ (retrieval/architecture/workflows question sets +
  semble-vs-graphify.md comparison methodology), scored on retrieval
  accuracy, source correctness, token consumption, completeness,
  hallucination rate.
• (Graphify / per-repo knowledge graphs were already in place before this work.)

Testing

This is a template/tooling repo — no application test suite. Verified by
running the actual scripts against the repo's own state at every step:

• node scripts/validate-ai-config.mjs — PASS (5/5 .ai/*.yaml files)
• node scripts/validate-knowledge.mjs — PASS (3 docs)
• node scripts/detect-doc-drift.mjs — runs clean (4 expected warnings: the
  template's illustrative acme-* vs example-* repo names intentionally
  don't match, demonstrating the drift check works)
• node scripts/check-adr-requirement.mjs main HEAD — PASS (no protected
  paths touched by this PR)
• node scripts/build-knowledge-index.mjs / generate-architecture-views.mjs
  — output committed and verified fresh
• Found and fixed a real bug in scripts/lib/yaml-lite.mjs while writing
  evals/*.yaml (block-sequence items that are multi-key mappings were
  silently truncated) — added regression coverage via the eval files
  themselves parsing correctly.

Risks

• Machine-readable policy (.ai/policies.yaml) is enforced by CI only for
  the ADR-on-protected-path case; forbidden/approval-required actions and
  agent-role scoping are documented but not yet mechanically enforced —
  called out explicitly in POLICY.md's new "Enforcement status" table so
  it doesn't read as more automated than it is.
• .ai/systems.yaml/commands.yaml/ownership.yaml still ship with
  illustrative example values (mirroring the existing AGENTS.md TODO
  pattern) — flagged in the Customization checklist, not silently assumed.

Documentation

This PR is documentation/tooling infrastructure — README.md,
knowledge/README.md, AGENTS.md, and POLICY.md were all updated in
place as part of the relevant phase.

ADR

Not required — this PR is the devrig template's own tooling/process
evolution, not a change to a project built on it. (Once a real project adopts
this and runs the Semble-vs-Graphify eval, that verdict should become an ADR.)

Rollback

Revert the merge commit; nothing here touches runtime code or has migration
side effects. The generated files (knowledge/index.md,
knowledge/generated/*.md) regenerate deterministically from source if regenerated post-revert.