scaffold: `codev init` bootstraps empty `codev/resources/` with arch.md + lessons-learned.md starters

[amrmelsayed]

Project-specific bootstrap gap. codev init does not create codev/resources/, so fresh projects have no arch.md or lessons-learned.md files. PIR / SPIR / ASPIR / MAINTAIN review prompts then fail on their first Read the current codev/resources/arch.md step. This is a separate concern from the framework-file resolution work in #1011 — these files are project-specific (each workspace's own architecture and lessons), not framework defaults the resolver should fall back to.

Bug

In a fresh codev init project:

• codev/specs/, codev/plans/, codev/reviews/, codev/projects/ exist (created by createUserDirs in packages/codev/src/lib/scaffold.ts:23-44).
• .codev/config.json exists.
• CLAUDE.md / AGENTS.md exist.
• codev/resources/ does not exist.
• codev/resources/arch.md does not exist.
• codev/resources/lessons-learned.md does not exist.

These files are referenced by review prompts across multiple protocols:

codev-skeleton/protocols/pir/prompts/review.md:61, :67, :88, :97, :98
codev-skeleton/protocols/spir/prompts/review.md:151, :152, :157, :158
codev-skeleton/protocols/aspir/prompts/review.md:151, :152, :157, :158
codev-skeleton/protocols/maintain/protocol.md  (heavy — MAINTAIN's primary write targets)
codev-skeleton/protocols/maintain/prompts/maintain.md:35, :54, :64
codev-skeleton/protocols/maintain/prompts/review.md:22

In particular, spir/prompts/review.md:152 says "Read the current codev/resources/arch.md" with no existence-conditional. In a fresh project, the first PIR / SPIR / ASPIR review phase hits this read, the file doesn't exist, the read errors. The protocol's graceful-degradation language ("if no changes needed, write 'no changes'") covers the no-content-to-update case but not the file-not-present-at-all case.

Why this is not the same bug class as #1011

arch.md and lessons-learned.md are project-specific. Each Codev workspace's architecture and lessons-learned content is unique to that project — that's the whole point. The skeleton should NOT provide a default arch.md for the resolver to fall back to (every workspace would inherit the same generic content, which defeats the purpose).

The correct fix is bootstrap on init, not resolver-fallback. codev init should create empty (or minimally-templated) starter files in codev/resources/ so the first review phase's read succeeds against a real, locally-owned file.

Fix

Extend createUserDirs (or add a sibling createResourcesDir) in packages/codev/src/lib/scaffold.ts to also create:

• codev/resources/ directory

• codev/resources/arch.md with a minimal starter:

  # Architecture
  
  This document evolves as the project grows. Update it during the review phase of any work that introduces or changes architectural patterns.
  
  _No architecture documented yet._

• codev/resources/lessons-learned.md with a minimal starter:

  # Lessons Learned
  
  Durable engineering wisdom captured across the project's work. Update it during the review phase of any work that surfaces a generally-applicable pattern, gotcha, or constraint.
  
  _No lessons captured yet._

The starter content is intentionally trivial — enough to make the file exist and be readable, with a one-line invitation to grow it. The first review phase that does have something meaningful to record replaces the placeholder.

codev init updated to call the new bootstrap; the existing init.ts output already lists each created file with a + prefix, so the new files surface in the output naturally.

Acceptance criteria

• codev init creates codev/resources/, codev/resources/arch.md, codev/resources/lessons-learned.md.
• Starter content is minimal and clearly marked as a placeholder ready to be replaced.
• codev adopt (existing-project flow) does NOT clobber existing resources/* files — preserve customizations. Create only what's missing.
• codev update (existing-project flow) does NOT touch resources/* — these are project-owned files.
• Existing scaffold tests updated; new test confirms init produces a working codev/resources/ layout.
• Manual verification: in a fresh codev init project, the first PIR / SPIR review phase that hits Read the current codev/resources/arch.md succeeds and reads the starter content.

Out of scope

• Framework-file literal-path resolution (protocol.md, templates, workflow-reference). Tracked in scaffold: deliver framework files (protocol.md, templates, workflow-ref) via resolver-aware channels (fresh-install class fix) #1011.
• Restoring full framework file copying. Tracked in Restore framework file copying on codev init / codev update — Spec 618 left builders without local protocol files in fresh installs #738.
• Migrating existing projects that happen to have an unusual codev/resources/ shape. The bootstrap only runs on init; adopt and update are no-ops for resources.

Suggested protocol

BUGFIX. Mechanically small (~10-20 LOC across scaffold.ts and init.ts, plus one or two test updates), no design discussion needed, no plan-gate value. The starter content is the only judgment call and it's a one-time write.

Related

• Restore framework file copying on codev init / codev update — Spec 618 left builders without local protocol files in fresh installs #738 — framework file copying strategic question. Tangentially related; this is the project-specific corollary.
• scaffold: deliver framework files (protocol.md, templates, workflow-ref) via resolver-aware channels (fresh-install class fix) #1011 — framework-file literal-path resolution. Companion fix from the same audit; addresses the framework side, this issue addresses the project-bootstrap side.