Genesis 2.0

A local-first, human-governed operating engine for turning opportunities into bounded experiments, reviewed evidence, and explicit business decisions.

Genesis guides one complete governed validation lifecycle: opportunity, evidence, preregistration, Human Authority review, manual activation, execution evidence, measurement, reflection, outcome decision, closure, and separately governed continuation. Every write is shown as a proposal and requires explicit confirmation.

Policy-Version: 2.0.1
Authority: Explanatory

Current release status: Version 2.0.0 is validated, Apache-2.0 licensed, and available as a verified local npm tarball. Public npm publication has not been authorized or performed.

What Genesis does
What Genesis does not do
How the engine works
Requirements
Quick start
Complete walkthrough
Command reference
How data is stored
Status and metrics
Safety, authority, and privacy
Recovery and troubleshooting
Repository architecture
Policy and record model
Development and verification
Current limitations
Project status and next steps
License

What Genesis does

Genesis 2.0 provides a working guided command-line workflow for Discover → experiment planning → Human Authority review → manual start → execution evidence → measurement → reflection → outcome decision → closure → governed continuation.

It can:

register a business opportunity with a target customer, problem, hypothesis, confidence, alternatives, expected outcome, metric, owner, and review date;
capture an initial evidence item while creating the opportunity;
append supporting or contradicting evidence with source references and provenance;
preserve decisions, evidence, experiments, and approvals as immutable, versioned YAML records;
require confirmation before writing any proposed record;
enforce JSON Schema and policy-derived workflow gates;
calculate early discovery and preregistration metrics;
create a complete validation-experiment proposal with explicit cash, labor, duration, data, and risk limits;
display the complete experiment and approval envelope for human review;
record explicit approval or denial by genesis-owner, with actor, scope, limits, effective time, expiry, and revocation checks;
require a separate manual command to move an exactly approved experiment to active;
record completed or stopped execution as a new immutable experiment version, including deviations and actual exposure;
reject execution evidence outside the approved actor, time, cash, labor, duration, data, or risk envelope;
record measurement separately with an analyst reviewer, source references, baseline comparison, and data-quality limitations;
create a reviewed experience with reflection, a reusable lesson, a validity window, and an explicit confidence update;
require Human Authority approval for one exact Major Bet outcome decision, backed by evidence, constitution, and CEO reviews;
close the experiment, business decision, and reviewed experience together after revalidating the exact outcome approval;
create a fresh Discover workflow after an eligible closed pivot or scale, linked to the reviewed experience but carrying forward no authority or limits;
create a separately budgeted Learning Lab after a real failed initiative classified learning_lab;
show every opportunity, its next action, review timing, and first blocker through genesis list;
search immutable evidence and reviewed experiences using literal keywords and bounded field filters;
accept JSON proposal input and emit machine-readable JSON for read-only operator commands;
correct discovery mistakes and revise draft experiments through append-only superseding versions;
revoke an approval and supersede an active experiment without deleting history;
maintain a fast local SQLite projection; and
rebuild that projection entirely from canonical YAML records.

Genesis is useful when you want a disciplined, auditable way to answer:

Who is the customer?
What real problem are we trying to solve?
What evidence supports or contradicts our belief?
What bounded experiment would change the decision?
Has the Human Authority explicitly approved this exact experiment, actor, and limit envelope?
What was actually executed, at what exposure, and what changed from the plan?
What result was measured, against which baseline, and how trustworthy is the data?

What Genesis does not do

The CLI can record a valid approval and manually mark an approved experiment active, but it does not execute the experiment. It does not automatically research, contact customers, run experiment steps, build products, deploy software, bill customers, or operate a business.

It also does not currently provide:

a graphical or web interface;
autonomous agents or external API calls;
automatic approval, authority inference, or automatic workflow progression;
automatic experiment task execution after the manual active transition;
automatic reflection, outcome selection, or closure;
customer relationship management, outreach, deployment, billing, or production operations; or
automatic Git/network operations, automatic semantic conflict resolution, or a hosted database.

The policy layer describes a broader governed business lifecycle. The implemented CLI records one complete governed validation path through closure while keeping the underlying experiment work and any follow-on outcome execution outside the engine.

How the engine works

flowchart LR
    U[Human operator] -->|answers prompts| C[Genesis CLI]
    C --> P[Proposal preview]
    P -->|explicit yes| V[Schema and policy checks]
    P -->|no| X[No change]
    V -->|valid| Y[(Immutable YAML records)]
    V -->|invalid| E[Actionable error\ncode · path · correction · escalation]
    Y --> S[(SQLite projection)]
    Y --> M[Status and metrics]
    S --> M
    Y -->|rebuild-index| S

The design has four important properties:

Local-first: normal CLI operation uses no network-capable imports or fetch calls.
Human-confirmed: every mutation displays the proposed record before asking whether to save it.
Append-only: a prior YAML record is never silently overwritten; changes create a new numbered version.
Recoverable: SQLite is derived data. Canonical YAML remains usable if the projection is missing or stale.

The current user journey is:

flowchart TD
    Start([Start]) -->|genesis start-business| Discover[Discover]
    Discover -->|genesis add-evidence| Discover
    Discover -->|genesis correct-decision| Discover
    Discover -->|discover gate passes| ExperimentPlan[Experiment plan]
    ExperimentPlan -->|genesis plan-experiment| ApprovalPending[Approval pending]
    ApprovalPending -->|genesis revise-experiment| ApprovalPending
    ApprovalPending -->|genesis approve-experiment| Approved[Approved]
    ApprovalPending -->|genesis deny-experiment| Denied[Denied]
    Approved -->|genesis start-experiment| Active[Active]
    Active -->|genesis record-execution| Measurement[Measurement]
    Measurement -->|genesis record-measurement| Reflection[Reflection]
    Reflection -->|genesis record-reflection| Decision[Decision]
    Decision -->|genesis decide-experiment| OutcomeApproved[Outcome approved]
    OutcomeApproved -->|genesis close-experiment| Closed[Closed]
    Closed -->|genesis start-follow-up| Discover
    Closed -->|genesis start-learning-lab| Discover
    Approved -->|genesis revoke-approval| Revoked[Revoked]
    Active -->|genesis revoke-approval| Superseded[Superseded]
    Active -.-> Note["Genesis records completed work;<br/>it does not run the experiment."]

Requirements

Node.js 22 or newer
npm
OpenSSH ssh-keygen with -Y sign and -Y verify support
A local filesystem supported by better-sqlite3

Check your versions:

node --version
npm --version

Quick start

Clone and install the locked dependencies:

git clone https://github.com/zee-cpu/Genesis.git
cd Genesis
npm ci

See the available commands:

node bin/genesis.mjs --help
node bin/genesis.mjs --version

For an existing opportunity, the guided operator path is:

genesis list
genesis next <business-id>

It reads the SQLite lifecycle projection, cross-checks canonical records, explains the current state, supplies safe record defaults, and asks only for information the next transition still requires.

Run directly from this repository:

npm start

For normal use from another project directory, link the local executable once:

npm link
mkdir my-opportunity-workspace
cd my-opportunity-workspace
genesis --help

Genesis always creates its .genesis/ workspace in the current working directory. Run commands from the directory that should own the business records.

To build and smoke-test the installable release-candidate tarball:

node scripts/verify-package.mjs --output artifacts
npm install --global ./artifacts/genesis-governance-2.0.0.tgz
genesis --version

The tarball contains only runtime code, normative configuration, schemas, templates, license notices, and user documentation. It excludes the landing page, experiments, tests, internal approval records, and historical review artifacts. Public npm publication is not yet authorized; see RELEASING.md.

Start your first opportunity:

genesis start-business

Before the first Human Authority approval in each workspace, establish the physical signing key:

genesis identity setup
genesis identity status

Genesis shows the SSH fingerprint and asks once before saving the append-only trust anchor. It stores the public key and signed identity events, never the private key.

For a passphrase-protected key, unlock it in your terminal and give Genesis the public-key path:

ssh-add ~/.ssh/genesis_owner_ed25519
genesis identity setup --signing-key ~/.ssh/genesis_owner_ed25519.pub

See Cryptographic Human Authority for the threat model, revocation behavior, compatibility rules, and trust boundary.

The CLI asks questions, prints the complete proposed records, and finishes with:

Save this immutable record? [y/N]

Nothing is saved unless you explicitly answer y, yes, true, or 1.

Complete walkthrough

The following example evaluates whether an order-reconciliation tool is worth testing with independent bakery owners.

1. Register the opportunity

genesis start-business

You will be prompted for:

Input	Meaning	Example
Business ID	Stable URL/file-safe opportunity identifier	`bakery`
Target customer	Specific customer segment	`Independent bakery owners`
Problem	Observable customer problem	`Weekly order reconciliation takes too long`
Hypothesis	Belief that a test could support or weaken	`A clearer order view reduces reconciliation time`
Confidence	Current probability-like belief from 0 to 1	`0.55`
Source reference	Traceable evidence pointer	`interview://owner-1`
Evidence summary	Short factual summary	`Owner spends two hours reconciling orders weekly`
Stance	Whether the item supports or contradicts the hypothesis	`support`
Provenance	How the evidence was obtained	`Interview note`
Privacy classification	Handling class for the record	`internal`
Counterevidence	Known objections or contrary observations	`Learning curve may offset savings`
Alternatives	Competing options, including doing nothing	`manual process, spreadsheet template`
Expected outcome	Outcome that would matter	`Reconciliation takes under one hour`
Metric	Measure used to judge the belief	`weekly_reconciliation_minutes`
Decision	Decision this discovery work supports	`run_bounded_validation`
Owner	Accountable role or person	`research`
Review date	When the decision should be revisited	`2026-07-24T12:00:00Z`

After confirmation, Genesis writes two records:

.genesis/records/evidence/bakery-evidence-001.v0001.yaml
.genesis/records/decisions/bakery-decision.v0001.yaml

2. Add more evidence

genesis add-evidence bakery

Record both support and contradiction. Contradicting evidence is not treated as failure; it is preserved so the decision can change when reality changes.

After confirmation, Genesis appends one evidence record and creates a new decision version:

.genesis/records/evidence/bakery-evidence-002.v0002.yaml
.genesis/records/decisions/bakery-decision.v0002.yaml

3. Inspect status

genesis status bakery

Typical output includes:

Business ID: bakery
State: discover
Next command: plan-experiment
Decision versions: 2
Experiment versions: 0
Evidence count: 2
Supporting evidence: 1
Contradicting evidence: 1
Discover gate: passed
Projection consistent: yes

The Discover gate requires a target customer, problem, hypothesis, and at least one confirmed evidence entry.

4. Preregister the experiment

genesis plan-experiment bakery

Genesis asks you to define the experiment before results exist:

the decision the experiment supports;
owner, baseline, and comparison method;
exact metric formula, population, denominator, and data source;
expected outcome and minimum meaningful effect;
failure and stop conditions;
maximum cash, labor hours, and duration;
permitted data classes and risk level;
decision date; and
allowed outcomes: scale, pivot, learning_lab, archive, or kill.

After confirmation, Genesis writes:

.genesis/records/experiments/bakery-experiment.v0001.yaml

The opportunity then enters approval_pending. A complete plan is not treated as approval or execution; it must pass the separate review and authority steps below.

5. Review the exact approval envelope

genesis review-experiment bakery

This is read-only. It shows the experiment, proposed approval action, execution actor, cash/labor/duration/data/risk limits, supporting evidence snapshot, effective time, and expiry. Review it before making an authority decision.

6. Approve or deny as Human Authority

To approve:

genesis approve-experiment bakery

To deny instead:

genesis deny-experiment bakery

Genesis asks for the approver principal, requester, rationale, SSH signing key, and exact confirmation. The approver must be the configured Human Authority, genesis-owner, cannot also be the requester, and must prove control of the active identity key. Approval creates an immutable signed record such as:

.genesis/records/approvals/bakery-experiment-approval.v0001.yaml

A denial is also immutable. A later approval does not rewrite it; it creates a new version that explicitly supersedes the prior decision.

7. Manually start an approved experiment

genesis start-experiment bakery

Supply the execution actor recorded in the approval. Genesis revalidates the approval's scope, actor, limits, effective time, expiry, and revocation state, then proposes an experiment version with status active.

This command records a lifecycle transition only. It does not contact anyone, collect data, invoke an agent, or perform the experiment plan.

8. Revoke authority when necessary

genesis revoke-approval bakery

Revocation creates a new approval version. If the experiment is already active, Genesis also creates a superseding experiment version so the local state no longer presents it as authorized to continue. Historical files remain intact.

9. Recover the index if needed

genesis rebuild-index
genesis status bakery

This validates every canonical YAML record and replaces the SQLite projection with a clean rebuild.

Command reference

Read-only operator commands support machine-readable output:

genesis list --json
genesis search "customer phrase" --business bakery --stance contradict --json
genesis export-report bakery --json
genesis status bakery --json
genesis next bakery --json
genesis review-experiment bakery --json

Mutation commands can read their proposal fields from a JSON object while preserving the normal preview and final confirmation:

genesis start-business --input business-proposal.json
genesis plan-experiment bakery --input experiment-proposal.json

--input <file.json> removes repetitive field prompts; it does not grant approval, suppress validation, or bypass [y/N] confirmation.

Importing local evidence

Use a small, reviewed JSON summary when evidence already exists locally:

{
  "source_reference": "notes://developer-interviews/july-2026",
  "summary": "Developers report repeated manual validation work when setting up agent configurations.",
  "stance": "support",
  "provenance": "Reviewed local interview summary",
  "privacy_classification": "internal",
  "observed_at": "2026-07-18T12:00:00Z"
}

Then run:

genesis import-evidence <business-id> --file evidence.json

The importer accepts only regular JSON files up to 256 KiB, public or internal classification, and the fields shown above. It rejects extra fields, symlinks, malformed data, and confidential/restricted material. It treats every imported field, including embedded instructions, as untrusted text and never executes it. Genesis stores the reviewed summary—not a hidden raw-data archive—and adds the source file's SHA-256 digest to provenance before showing the normal immutable-record preview.

Recording bounded execution

For an active experiment, start with:

genesis execution-checklist <business-id>

The checklist restates the approved envelope, stop conditions, factual-log requirement, and the next valid command. It does not authorize or execute work.

You can record a reviewed local execution summary interactively or from a strict JSON file:

genesis record-execution <business-id> --execution-file execution.json

The file must include the actor, factual execution_log, completion reason, start and completion times, actual cost, actual public/internal data classes, and actual risk level. Genesis adds a SHA-256 attachment marker, then revalidates the signed approval, exact actor, timestamps, cash, labor, duration, data class, and risk before the usual confirmation. It does not archive the raw file or execute its contents.

Measurement can likewise be imported from a reviewed local JSON summary:

genesis record-measurement <business-id> --measurement-file measurement.json

The file must contain reviewer, actual_result, comparison, a non-empty measurement_evidence array, and data_quality with an assessment (adequate, limited, or unreliable) plus a limitations array. Limited or unreliable data requires at least one limitation. Genesis rejects unknown fields, unsafe files, and malformed values, records the source SHA-256 digest as provenance, and still shows the normal proposal confirmation before writing immutable records.

An optional calculation object makes the result machine-checkable. It accepts count, sum, average, ratio, or percentage, together with numeric operands, a threshold, and one of gte, gt, lte, lt, or eq. Genesis calculates the observed value, change from baseline, whether the threshold was met, and a provisional passed or failed outcome. The later analyst reflection remains a separate review step and cannot be skipped.

The interactive genesis next <business-id> measurement step offers the same calculation as a short optional guided sequence. It asks only for values required by the selected method; operators can decline and preserve a qualitative reviewed result instead.

Command	Purpose	Writes records?	Expected end state
`genesis identity setup`	Establish the append-only `genesis-owner` SSH trust anchor after showing its fingerprint	Writes an identity event after confirmation	Identity verified
`genesis identity status`	Verify the current Human Authority identity chain and active key	No	Unchanged
`genesis identity revoke`	Sign and append revocation of the active Human Authority key	Writes an identity event after confirmation	New approvals blocked
`genesis verify-workspace`	Verify identity history and every runtime approval signature	No	Unchanged
`genesis sync status`	Inspect local records, prepared events, incoming resources, and conflicts	No	Unchanged
`genesis sync prepare`	Create deterministic content-addressed events for local records and identities	Derived events, after confirmation	Git-ready
`genesis sync apply`	Validate the merged event set, materialize unambiguous resources, and rebuild SQLite	Missing canonical resources, after confirmation	Converged or blocked
`genesis start-business`	Create an opportunity, its first decision, and initial evidence	Yes, after confirmation	`discover`
`genesis start-follow-up <business-id>`	Create a separately governed follow-up after a closed `pivot` or `scale`	Yes, after confirmation	New business in `discover`
`genesis start-learning-lab <business-id>`	Allocate a bounded Learning Lab after a closed, failed initiative classified `learning_lab`	Yes, after confirmation	New business in `discover`
`genesis add-evidence <business-id>`	Add evidence and version the associated decision	Yes, after confirmation	`discover`
`genesis import-evidence <business-id> --file <path>`	Validate and import one local public/internal JSON evidence summary through the normal evidence gate	Yes, after confirmation	`discover`
`genesis execution-checklist <business-id>`	Show a factual, read-only checklist for an active approved experiment	No	Unchanged
`genesis correct-decision <business-id>`	Correct mutable discovery fields by appending a reasoned decision version	Yes, after confirmation	`discover`
`genesis list`	List all projected opportunities with state, next action, review timing, and the first actionable blocker	No	Unchanged
`genesis search <query>`	Search immutable evidence and reviewed experiences by literal keyword, business, stance, or privacy class	No	Unchanged
`genesis export-report <business-id>`	Export a customer-readable Markdown report or a structured JSON lifecycle snapshot	No	Unchanged
`genesis status <business-id>`	Show state, gates, metrics, limits, blocked commands, and projection health	No	Unchanged
`genesis next <business-id>`	Explain the projected state and guide the next valid transition one question at a time	Only when the guided proposal is confirmed	Depends on current state
`genesis plan-experiment <business-id>`	Create a complete validation-experiment preregistration	Yes, after confirmation	`approval_pending`
`genesis revise-experiment <business-id>`	Correct a draft preregistration and require review of the new immutable version	Yes, after confirmation	`approval_pending` or `approval_denied`
`genesis review-experiment <business-id>`	Display the exact experiment and approval envelope for review	No	Unchanged
`genesis approve-experiment <business-id>`	Record an explicit Human Authority approval	Yes, after confirmation	`approved`
`genesis deny-experiment <business-id>`	Record an explicit Human Authority denial	Yes, after confirmation	`approval_denied`
`genesis start-experiment <business-id>`	Revalidate approval and manually mark the experiment active	Yes, after confirmation	`active`
`genesis record-execution <business-id>`	Preserve execution evidence and actual exposure inside the approved envelope	Yes, after confirmation	`measurement`
`genesis record-measurement <business-id>`	Preserve the observed result, comparison, sources, and data quality	Yes, after confirmation	`reflection`
`genesis record-reflection <business-id>`	Create a reviewed experience, reusable lesson, and confidence update	Yes, after confirmation	`decision`
`genesis decide-experiment <business-id>`	Record Human Authority approval for one exact Major Bet outcome	Yes, after confirmation	`outcome_approved`
`genesis close-experiment <business-id>`	Revalidate outcome approval and close linked experiment, decision, and experience records	Yes, after confirmation	`closed`
`genesis revoke-approval <business-id>`	Revoke approval and supersede an active experiment	Yes, after confirmation	`approval_revoked` or `superseded`
`genesis rebuild-index`	Validate YAML and rebuild SQLite from scratch	Replaces derived index only	Unchanged
`genesis --help`	Print command usage	No	Unchanged

Exit codes:

Code	Meaning
`0`	Command completed or the user cancelled a proposal
`1`	Validation, workflow, storage, or unexpected execution error
`2`	Unknown command or missing required command argument

How data is stored

Genesis creates this structure in the directory where you run it:

.genesis/
├── identities/
│   └── genesis-owner-identity.v0001.yaml
├── records/
│   ├── decisions/
│   │   └── <decision-id>.v0001.yaml
│   ├── evidence/
│   │   └── <evidence-id>.v0001.yaml
│   ├── experiments/
│   │   └── <experiment-id>.v0001.yaml
│   ├── experiences/
│   │   └── <experience-id>.v0001.yaml
│   └── approvals/
│       └── <approval-id>.v0001.yaml
├── .transactions/        # transient crash-recovery journals, normally empty
├── sync/
│   └── events/           # Git-trackable content-addressed event set
├── genesis.db
└── workspace.lock        # exists only while an operation is active

Canonical YAML

YAML records are the source of truth. They are:

schema-validated before persistence;
staged, synced, and installed with no-replace semantics;
permissioned locally (0600 files and 0700 directories where supported);
versioned with .v0001.yaml, .v0002.yaml, and so on; and
protected from accidental overwrite by rejecting an existing version path.

Do not edit historical records to change what happened. Create a new version or a superseding record through the appropriate workflow.

Rebuildable SQLite projection

.genesis/genesis.db is a query-oriented cache containing:

every projected record version;
current opportunity state and latest record references;
approval decisions, status, actor, scope, limits, and validity dates;
support and contradiction counts;
confidence and lifecycle timestamps; and
blocked command events.

SQLite is not authoritative. If projection fails after YAML is safely written, Genesis reports PROJECTION_STALE; the data remains recoverable with genesis rebuild-index.

Conflict-safe team sync

Genesis synchronizes data, not Git credentials or network access. The shared directory is a grow-only, content-addressed event set—a G-Set CRDT—under .genesis/sync/events/. Each event embeds one schema-valid canonical record or signed identity event. Its filename, event identifier, logical path, and payload digest must all agree.

Before committing local changes:

genesis sync status
genesis sync prepare
git add .genesis/sync/events
git commit -m "sync Genesis records"

After using your normal Git workflow to pull or merge another teammate's events:

genesis sync status
genesis sync apply
genesis verify-workspace

sync prepare and sync apply each show one direct confirmation. Genesis never runs git, contacts a remote, or pushes for you. sync apply first validates every event, reconstructs the merged view in a temporary workspace, verifies identity history and signed approvals, and proves that SQLite can be rebuilt. Only then does it install missing canonical YAML with no-replace semantics and rebuild the local projection.

Events with different identifiers merge by set union. If two peers create different payloads for the same immutable logical version, both events are preserved and Genesis reports SYNC_CONFLICT; neither payload is selected automatically. Stop and request a separate Human Authority reconciliation decision—automated conflict resolution is intentionally outside this milestone. Sync events contain the complete record payload, including its privacy classification, so review data scope before committing them to any repository.

Workspace locking

Genesis creates .genesis/workspace.lock with exclusive creation while it reads or writes the workspace. A competing operation fails with WORKSPACE_LOCKED, preventing concurrent local commands from racing. If a terminated process leaves a well-formed lock behind, Genesis verifies that the recorded PID is no longer active and reclaims the lock automatically. Ambiguous locks fail closed for manual inspection.

Status and metrics

genesis status <business-id> combines canonical records with the SQLite projection and reports:

lifecycle state and next permitted command;
decision, evidence, experiment, and approval counts;
supporting and contradicting evidence totals;
Discover-gate result and blockers;
missing experiment-preregistration fields;
cash, labor, duration, data, and risk limits;
latest approval decision, status, execution actor, expiry, validity, and exact blockers;
blocked commands grouped by error code;
YAML/SQLite projection consistency;
discovery duration;
time to validation plan;
preregistration completeness ratio; and
confidence history across decision versions.

genesis list is the read-only operator inbox. It reads opportunity identities and projected states from SQLite, verifies the index against canonical YAML, and shows the next guided action, nearest applicable review, and first actionable blocker. genesis next <business-id> then handles one selected opportunity. It fails closed when the projection is missing or inconsistent, derives safe values such as supported-decision references and approval timestamps, and routes the resulting proposal through the same schema, approval, append-only storage, and projection checks as the direct commands. A closed failed initiative classified learning_lab is routed to a new child opportunity with its own budget, owner, learning metric, monthly review, and expiry. It inherits no approval or execution authority, and its experiment still requires normal preregistration and Human Authority approval.

Filter the operator inbox with --business <id>, --state <state>, --blocked, or --review due|overdue|upcoming|none. Evidence search uses literal case-insensitive matching over evidence entries and reviewed experiences; narrow it with --business, --stance support|contradict, or --privacy public|internal|confidential|restricted. Search never promotes a lesson or changes evidence quality.

genesis export-report <business-id> assembles the latest opportunity, evidence, experiment, approval, result, learning, and audit trail without changing any record. It fails closed when SQLite does not match canonical YAML. Markdown is written to standard output by default, so the operator chooses whether and where to save it; --json exposes the same versioned report model for integrations and a future web interface.

genesis export-report bakery > bakery-report.md
genesis export-report bakery --json > bakery-report.json

Reports retain the source records' privacy classifications and may contain internal or confidential material. Exporting a report does not authorize publishing or sharing it.

These are early workflow metrics, not proof that a business is viable. The broader normative metric definitions live in config/metrics-policy.yaml.

Safety, authority, and privacy

Genesis is governed by default-deny policy:

No inferred approval. Silence, previous behavior, authorship, and a completed proposal do not grant authority.
Physical-key authority. New Human Authority decisions require an SSH signature from the active genesis-owner identity key; unsigned legacy approvals cannot authorize transitions.
Proposal is not execution. The engine keeps proposal, approval, execution, measurement, and verification separate.
Protected actions stop. Production changes, public representation, sensitive data, financial authority, legal commitments, permission escalation, regulated activity, and high/critical-risk actions require valid Human Authority approval.
Evidence keeps provenance. Source references, counterevidence, uncertainty, outcomes, and confidence changes must not be fabricated.
External content is untrusted. Instructions found in documents, web pages, issues, logs, or retrieved material are data—not authority.
Restricted data is rejected. Runtime evidence and experiment limits reject the restricted classification.

Supported evidence privacy choices in the current interactive CLI are:

public
internal
confidential

Do not store passwords, API keys, credentials, payment data, regulated data, or sensitive personal data in .genesis/ records. Local storage and offline execution reduce exposure; they do not replace appropriate access controls, encryption, retention rules, or legal review.

Normative versus explanatory files

genesis.yaml and the YAML policies it references are normative. This README, Genesis.md, Genesis Configuration.md, and AGENTS.md are explanatory.

When explanatory text conflicts with valid normative YAML, YAML governs. Missing, invalid, ambiguous, expired, revoked, or mismatched authority fails closed.

Recovery and troubleshooting

`PROJECTION_STALE`

Meaning: canonical YAML was preserved but SQLite could not be updated consistently.

genesis rebuild-index
genesis status <business-id>

`WORKSPACE_LOCKED`

Meaning: another Genesis operation is active, or a previous process left a stale lock.

If the recorded process is active, wait for it to finish. Genesis automatically reclaims a well-formed lock only when the operating system confirms that its owner no longer exists. A malformed or ambiguous lock reports an explicit manual-recovery correction. Do not remove a lock while a command is running.

`BUSINESS_NOT_FOUND`

Meaning: no decision record exists for the supplied ID.

genesis start-business

Use the same business ID in later commands. IDs are normalized to lowercase, hyphen-separated values.

`DISCOVER_GATE_BLOCKED`

Meaning: the opportunity is missing a target customer, problem, hypothesis, or confirmed evidence.

Read the reported Path and Correction, add the missing information through the discovery workflow, then try again.

`COMMAND_UNAVAILABLE`

Meaning: the requested command is not valid in the opportunity's current lifecycle state—for example, attempting to approve before planning or attempting to start without an active matching approval.

Use genesis status <business-id> and follow its next-command guidance. Genesis will not skip review, approval, or manual-start boundaries.

Approval validity errors

Errors such as APPROVAL_EXPIRED, APPROVAL_REVOKED, APPROVAL_SCOPE_MISMATCH, APPROVAL_ACTOR_MISMATCH, and APPROVAL_LIMIT_MISMATCH mean the approval cannot authorize the requested transition.

Read the reported path and correction. Do not edit the historical YAML. Create the appropriate new approval decision through the CLI or escalate to genesis-owner when authority is missing or ambiguous.

`RECORD_SCHEMA_INVALID`

Meaning: a canonical record does not match its registered schema or contains invalid YAML.

The error reports the affected path and correction. Preserve the invalid file for investigation; do not silently rewrite history.

Native dependency installation fails

better-sqlite3 may require a compatible Node.js version and build environment when a prebuilt binary is unavailable. Confirm that Node.js 22+ is active, remove no canonical .genesis/ data, and rerun:

npm ci

Repository architecture

Genesis/
├── bin/                         CLI executable
├── src/
│   ├── cli/                     prompts, rendering, command dispatch
│   ├── application/             workflow orchestration service
│   ├── core/                    gates, records, metrics, IDs, errors
│   ├── security/                canonicalization, SSH identity, signatures
│   ├── sync/                    content-addressed events and safe reconciliation
│   └── storage/                 YAML store, SQLite projection, locking
├── config/                      normative governance and workflow policy
│   └── workflows/               business and experiment state machines
├── schemas/                     strict JSON Schemas for policy and records
├── templates/                   record examples; never implicit approvals
├── records/approvals/           repository action approval evidence
├── scripts/                     full policy/schema validation
├── tests/                       unit, integration, invariant, offline, recovery
├── docs/                        historical reviews and verification evidence
├── .github/workflows/           locked CI validation gate
├── genesis.yaml                 normative manifest and policy registry
├── Genesis.md                   human-readable constitution
├── Genesis Configuration.md     maintainer configuration guide
└── AGENTS.md                    repository-wide agent conduct

Runtime dependency flow:

graph TD
    B[bin/genesis.mjs] --> CLI[src/cli]
    CLI --> APP[src/application]
    APP --> CORE[src/core]
    APP --> STORE[src/storage]
    CORE --> SCHEMA[schemas + config]
    STORE --> YAML[(versioned YAML)]
    STORE --> DB[(SQLite projection)]

Main modules

Module	Responsibility
`src/cli/run-cli.mjs`	Parses commands, gathers input, requests confirmation, and maps failures to exit codes
`src/application/genesis-service.mjs`	Builds proposals, applies gates, serializes operations, persists records, and returns status
`src/core/record-builders.mjs`	Constructs and validates evidence, decision, experiment, and approval records
`src/core/approval-workflow.mjs`	Evaluates exact approval scope, actor, limits, authority, effective time, expiry, and revocation state
`src/core/discovery-workflow.mjs`	Evaluates the Discover gate, preregistration completeness, state, and next command
`src/core/metrics.mjs`	Calculates local workflow metrics from record history
`src/core/schema-registry.mjs`	Loads registered schemas and performs strict runtime validation
`src/storage/yaml-record-store.mjs`	Performs append-only, atomic batch persistence and interrupted-transaction recovery
`src/storage/projection.mjs`	Creates, updates, checks, and rebuilds the SQLite projection
`src/sync/sync-store.mjs`	Prepares the grow-only event set, detects divergence, validates merged state, and safely materializes incoming resources
`scripts/validate-genesis.mjs`	Validates the normative manifest, schemas, references, documents, and cross-file invariants

Policy and record model

Genesis separates three layers:

Layer	Purpose	Examples
Normative policy	Defines what is valid and authorized	`genesis.yaml`, `config/*.yaml`, workflow YAML
Canonical records	Preserves proposals, decisions, evidence, experiments, and approvals	`.genesis/records/*/.yaml`, `records/approvals/*.yaml`
Derived views	Makes canonical records convenient to inspect	`.genesis/genesis.db`, CLI status output

The normative policies cover:

governance and Human Authority;
organization and separation of duties;
low-risk permissions and protected actions;
decision classes and approval thresholds;
portfolio limits and anti-meta-work controls;
business and experiment lifecycle transitions;
experience/knowledge promotion;
risk, privacy, security, financial, and AI controls; and
measurement definitions and Genesis Experiment #001.

Record schemas cover approval, decision, experiment, experience, constitutional amendment, and runtime evidence records. Templates demonstrate valid structure but never grant approval.

Development and verification

Install exactly what is recorded in package-lock.json:

npm ci

Run policy and schema validation:

npm run validate

Run the Node.js test suite:

npm test

Run the complete local gate:

npm run check

The test suite covers:

manifest, schema, reference, and documentation validation;
governance and policy invariants;
valid and intentionally invalid records;
lifecycle gates, metrics, and record construction;
CLI command dispatch and a complete interactive flow;
immutable versions, atomic writes, and workspace locking;
SQLite projection and consistency checks;
stale-projection and corrupted-index recovery;
fail-closed behavior; and
absence of network-capable imports and runtime fetch use.

GitHub Actions runs npm ci, npm run validate, and npm test for pull requests and pushes to main.

Making a normative change

Identify the external decision, actor, lifecycle state, authority, budget, duration, data, and risk envelope.
Read genesis.yaml and every affected normative policy.
Obtain any required explicit approval before a protected or constitutional action.
Update the normative YAML, matching JSON Schema, and tests together.
Update explanatory documentation only after the normative behavior is correct.
Run focused tests, then npm run check.
Review the diff and preserve relevant evidence before publication.

Do not change Markdown in an attempt to override policy.

Current limitations

Genesis 2.0 is a complete governed validation CLI and a practical foundation for a broader business operating engine. It deliberately stops before autonomous execution and production operations.

Current technical boundaries include:

structured input is JSON-file based and still requires interactive confirmation; there is no unattended approval mode;
one process per local workspace operation; peers exchange events through an operator-managed Git workflow;
corrections are intentionally limited to discovery decisions and draft experiments; evidence and active/completed lifecycle records remain immutable;
terminal-driven review only; Human Authority is SSH-verified, but other operator roles are still locally entered and type-checked;
the initial key bootstrap is trust-on-first-use and requires out-of-band fingerprint review for shared workspaces;
signatures detect record modification but cannot prevent deletion by a fully compromised local account, and local timestamps are not trusted timestamp-authority proofs;
the active transition records authorization state but does not run experiment tasks;
execution and measurement are operator-entered evidence; Genesis does not infer or fabricate results;
an approved scale, pivot, or other outcome is a classification decision only; it grants no permission to execute follow-on work;
generic follow-up is limited to closed pivot and scale outcomes; Learning Lab continuation is limited to a real failed initiative and must fit its separately recorded budget, owner, metric, monthly review, and expiry;
no automatic metric ingestion from customer or operating systems;
sync transport is operator-managed Git: Genesis does not encrypt events, authenticate Git users, manage remotes, push, pull, or back up repositories;
concurrent edits to the same immutable logical version deliberately require Human Authority resolution rather than automatic winner selection;
an installable Apache-2.0 release-candidate tarball is verified locally, but public npm publication remains pending explicit Human Authority approval; and
no full autonomous business execution.

Treat the broader policies as the target governance contract and the current CLI as the first enforceable vertical slice.

Project status and next steps

The current engine is ready for local, controlled use across one complete governed validation lifecycle: opportunity, evidence, preregistration, approval, activation, execution evidence, measurement, reflection, Major Bet outcome decision, experience preservation, and closure. The most valuable next product increments are:

Customer-reality integrations: import approved evidence without granting retrieved content authority.
Public release authorization: authorize the exact package, registry, version, actor, and publication window before enabling npm publication.
Broader operator identity: extend verified identity beyond Human Authority before any hosted or multi-user use.
Read-only web control interface (paused): visualize the same signed and synchronized backend state locally.

The guiding rule is simple: automate only what has been understood manually, and measure success through better external decisions—not more internal artifacts.

License

Original Genesis code and documentation are licensed under the Apache License 2.0, copyright 2026 zee-cpu. The license does not grant trademark rights. Third-party dependencies remain governed by their respective licenses; see NOTICE and the locked dependency metadata.

For policy interpretation, begin with genesis.yaml. For operating and maintenance guidance, read Genesis Configuration.md. For the human-readable governance model, read Genesis.md.

Name		Name	Last commit message	Last commit date
Latest commit History 30 Commits
.github/workflows		.github/workflows
apps/operator-console		apps/operator-console
bin		bin
business/offers/agent-configuration-repair		business/offers/agent-configuration-repair
config		config
docs		docs
records		records
schemas		schemas
scripts		scripts
site		site
src		src
templates		templates
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
Genesis Configuration.md		Genesis Configuration.md
Genesis.md		Genesis.md
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
RELEASING.md		RELEASING.md
codex.md.md		codex.md.md
genesis.yaml		genesis.yaml
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

Genesis 2.0

Table of contents

What Genesis does

What Genesis does not do

How the engine works

Requirements

Quick start

Complete walkthrough

1. Register the opportunity

2. Add more evidence

3. Inspect status

4. Preregister the experiment

5. Review the exact approval envelope

6. Approve or deny as Human Authority

7. Manually start an approved experiment

8. Revoke authority when necessary

9. Recover the index if needed

Command reference

Importing local evidence

Recording bounded execution

How data is stored

Canonical YAML

Rebuildable SQLite projection

Conflict-safe team sync

Workspace locking

Status and metrics

Safety, authority, and privacy

Normative versus explanatory files

Recovery and troubleshooting

PROJECTION_STALE

WORKSPACE_LOCKED

BUSINESS_NOT_FOUND

DISCOVER_GATE_BLOCKED

COMMAND_UNAVAILABLE

Approval validity errors

RECORD_SCHEMA_INVALID

Native dependency installation fails

Repository architecture

Main modules

Policy and record model

Development and verification

Making a normative change

Current limitations

Project status and next steps

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`PROJECTION_STALE`

`WORKSPACE_LOCKED`

`BUSINESS_NOT_FOUND`

`DISCOVER_GATE_BLOCKED`

`COMMAND_UNAVAILABLE`

`RECORD_SCHEMA_INVALID`

Packages