Project file scaffold (`.ragtech/project.json`)

[natashaannn]

Project file scaffold (.ragtech/project.json)

Objective

Create the foundational project-file layer used by all later pipeline and reproducibility work.

Deliver a typed ProjectFile interface plus helper functions for reading/writing .ragtech/project.json.

---

Why this matters

The current system has no persistent project model.

This issue creates the minimal shared foundation needed for:

• deterministic parameters
• artifact lineage
• brand selection
• future DAG execution

This is intentionally small and can land early.

---

Parallelization metadata

Track

infra

Depends on

• none

Safe to run in parallel with

• artifact store issue
• FFT determinism issue
• brand type extension issue

Merge risk

• low — mostly additive new files

---

Files in scope

Primary:

• scripts/config/project.ts

May touch minimally:

• package.json

Avoid touching:

• scripts/wizard.js

---

Required implementation

1. Define project types

• create ProjectFile

• include top-level fields:

  • version
  • episode
  • brandId
  • tools
  • params
  • artifacts

2. Add helpers

• readProject(cwd?: string): ProjectFile
• writeProject(project: ProjectFile, cwd?: string): void

3. Bootstrap behavior

• if .ragtech/project.json does not exist, create .ragtech/
• write formatted JSON

---

Constraints

• keep implementation synchronous
• no CLI behavior changes yet
• no migration logic yet

---

Handoff contract

Must expose stable imports:

import { readProject, writeProject } from '../config/project';

---

Acceptance criteria

Functional

• reading existing project file succeeds
• writing creates .ragtech/project.json

Unit tests

• read/write roundtrip preserves structure

Integration checks

• node -e "require('./scripts/config/project.ts')" runs without error

---

Verification commands

node -e "require('./scripts/config/project.ts')"

Expected result:

(no output, exits 0)

---

Explicitly out of scope

• artifact hashing
• CLI migration
• pipeline integration

---

Suggested branch

refactor/s1-project-file

Suggested commit slug

phase-0-step-1-project-file-scaffold