Projects

A project is where engineering happens. It is the container events belong to, the thing a repository links to, and the unit a timeline is drawn for. It is also, deliberately, one of the least powerful objects in Pulse: a project owns no identity, no reputation and no events of its own — it holds them.

In practice, a project maps to a codebase: atlas-gateway, orbit-sdk, ledger-core. It has a name, a slug, an owner, an optional organization, a set of technologies, a visibility, and — the part that makes it real — a linked repository. That link is the project's verification source. Without it, a project is a folder with a nice page; with it, everything that happens inside it can be proved.

Projects exist to give events a home that outlives their author. An engineer leaves; the project's timeline is intact. A repository is archived; the record of how it was built survives. A project is transferred from a founder to a company; every event that happened before the transfer stays attributed to the people who did it.

The tempting design is to make the project the center of gravity: it accumulates reputation, it holds the score, contributors borrow from it. We rejected that, and the reason is what happens when the project changes hands.

If reputation lived in the project, then transferring the project would transfer the credit — a company could acquire a codebase and inherit the standing of the engineers who built it, and those engineers would walk away with nothing. So credibility does not accumulate in the container. It flows through it, to the developers whose verified events produced it. The project's owner is polymorphic and transferable precisely because ownership of the container is a weak claim; authorship of the execution is the strong one, and it never moves.

• Slug — the project's stable address, used by the CLI and the URL: /pulse/projects/atlas-gateway.
• Owner — a developer or an organization. Polymorphic and transferable; the transfer is itself an event.
• Repository link — the verification source. One repository per project is the normal case.
• Visibility — public, or private to an organization. A private project's events can still be verified and still count.
• Timeline — the project's events in order. Append-only across the entire lifecycle, including archival.
• Fork — a project derived from another. The relationship is a derived_from edge, so lineage is preserved rather than lost.

1. You create a project — with pulse init, or in the Engineering Workspace.
2. You link a repository. From this point the project has a verification source and can attest events above L1.
3. Execution flows in. Pushes, deployments and releases from the linked repository land on the project timeline automatically.
4. Context flows in. BLOCKs, UNLOCKs and PIVOTs recorded against the project join the same timeline.
5. The project page projects all of it: timeline, contributors, technologies, resolution history and knowledge.
6. Credit flows out, to the developers who authored the verified events — never to the container.

A repository is where code lives. A project is where the record of engineering lives. They are usually one-to-one, but the distinction matters at the edges: a project can outlive its repository, a monorepo may carry several projects, and a project that has not yet linked a repository is legitimate — it simply cannot be verified strongly yet.

1. Create the project once, from the repository root.
2. Commit pulse.json so every contributor records into the same project rather than creating their own.
3. Wire pulse deploy into the deployment pipeline so releases capture themselves.
4. Record incidents and decisions against the project as they happen.
5. Review the project timeline before a planning cycle — it is a more honest input than anyone's memory.

cd ~/code/atlas-gateway

# Create the project and bind it to its organization
pulse init --project atlas-gateway --org northwind

# Give it a verification source
pulse link github.com/northwind/atlas-gateway

# Confirm what Pulse now knows about this project
pulse status

{
  "slug": "atlas-gateway",
  "name": "atlas-gateway",
  "owner": { "type": "organization", "slug": "northwind" },
  "repository": "github.com/northwind/atlas-gateway",
  "visibility": "public",
  "technologies": ["typescript", "node", "redis", "postgres"],
  "contributors": 6,
  "events": 148,
  "createdAt": "2025-11-03T09:00:00Z"
}

• One project per deployable unit. Resist the urge to create a project per team or per quarter — timelines get their value from being long.
• Link the repository on day one. Events recorded before the link exists cannot be retroactively raised to a higher trust level.
• Name the project after the codebase, not the initiative. The codebase will outlast the initiative.
• Transfer projects rather than recreating them. A fresh project starts with an empty timeline, which throws away the entire point.
• Archive instead of deleting. An archived project keeps its record readable; a deleted one takes its history with it.

• Every developer running pulse init in the same repository, producing four projects with the same name and four fragmented timelines. Init once; commit pulse.json.
• Creating a project for exploratory work, abandoning it, and leaving a dead container with two events. Prefer recording exploratory work as a PIVOT on an existing project.
• Expecting a project to have its own Build Cred. It does not. Projects carry activity and verification; people carry reputation.
• Assuming a fork resets lineage. A fork keeps a derived_from edge to its origin, on purpose — the history is part of what you forked.

• The project timeline is append-only across the full lifecycle. Archiving is an event, not an erasure.
• A project can be owned by a developer directly. An organization is not required.
• Private projects are fully supported and fully verifiable. What is hidden is the detail, not the proof — see Privacy Mask.
• Repositories and deployment pipelines are both verification sources. A project with both attests at a higher trust level than a project with one.