What is project-state? The Substrate That Runs an Engagement

Every engineering engagement generates a massive amount of knowledge. Slide decks get emailed. Decisions happen in meetings and vanish. Risk registers live in someone's head. Status reports are manually assembled from scattered spreadsheets.

project-state is the answer to that entropy. It's a structured facility — a directory of YAML, JSON, Markdown, and NDJSON files — that becomes the single source of truth for everything happening in an engagement.

The anatomy of a .project-state/ facility

.project-state/
├── manifest.yaml          # Who, what, why — the engagement identity
├── state.json             # Current phase, gates passed, open risks
├── SPINE.md               # The engagement model (ours is 5-phase)
├── intelligence/          # What we understand, organized by layer
│   ├── context.md         # Industry, client, competitive landscape
│   ├── solution.md        # What we're building and why
│   └── operational.md     # How it runs day-to-day
├── decisions/             # Every gate decision with rationale
├── stakeholders/          # People, orgs, influence maps
├── kpis/                  # Metrics by phase
├── logs/                  # Activity log (append-only NDJSON)
├── documents/             # Classified document registry
└── website/               # Dashboard that renders all of the above

Why not a database?

Databases are great for apps. They're terrible for engineering engagements. Here's why:

1. Files are portable. You can copy a .project-state/ directory to a USB drive, email it, or push it to Git. Try doing that with a Postgres schema.

2. Files are readable. Open manifest.yaml in any text editor and you know exactly what the engagement is. No ORM, no migrations, no query language.

3. Files are diffable. When a decision changes, git diff shows you exactly what changed and when. That's an audit trail for free.

4. Files are AI-friendly. An LLM can read YAML and Markdown natively. No API wrapper needed. The substrate is the context window.

The living layer

project-state isn't a template you fill in once and forget. It's a living system:

• Activity logs append every event as NDJSON — you never lose history
• Intelligence layers accumulate as you learn more about the client's domain
• Decisions capture not just what was decided, but why and by whom
• KPIs track outcomes phase by phase
• The website renders it all as a dashboard, updated on every deploy

When you add a document to the facility, it gets classified, indexed, and cross-referenced automatically. When you pass a gate decision, the state updates and the dashboard reflects it.

Who is this for?

project-state was built for technical engagements where the knowledge matters as much as the deliverable. Consulting firms, engineering services companies, R&D partnerships — anyone who needs to capture institutional knowledge as it's created, not reconstruct it after the fact.

For Daanaa Resolution, the engagement itself demonstrates the pattern: a structured substrate that captures everything, surfaces it through a dashboard, and grows smarter over time. The same architecture we're using to run this engagement is the architecture we're proposing for their product development process.

The substrate is the demo.