Project OS Builder

Evidence-first operating system for legacy websites.

Project OS Builder turns an expert-curated evidence manifest into a deterministic, reviewable handoff package:

• production, staging/control, and rollback posture;
• stable claims linked to explicit evidence;
• scoped gates and measurement epochs;
• components, history, runbooks, risks, conflicts, and authority;
• immutable snapshots and semantic diffs;
• a plain-language, print-ready executive report.

It is designed for old, valuable websites that are too risky to change from memory and too important to leave undocumented.

Status: public v0.1.1 design-partner release. The software is tested; paid delivery acceptance and measured business outcomes are not yet claimed.

The product boundary

This is a service-led system, not an autonomous truth-discovery crawler.

An expert selects evidence, models claims, defines authority, and interprets conflicts. The Builder makes that model reproducible, testable, diffable, and safe to hand off.

It never:

• connects to production;
• changes a CMS, hosting, DNS, SSL, analytics, or billing;
• auto-resolves conflicts;
• turns unavailable evidence into zero;
• treats READY_FOR_HANDOFF as production authorization;
• creates a public-safe client case automatically.

Why this is not ProofRank

Product	Primary job
Project OS Builder	Model the whole project: topology, evidence, decisions, history, rollback, risks, runbooks, and authority
ProofRank	Apply an optional evidence-sufficiency gate at selected decision boundaries
Managed Website OS	Operate the resulting system with ongoing expert supervision

ProofRank can run alongside Project OS Builder. It does not replace the private operating model.

Quick start

Requirements: Node.js 20+; no runtime dependencies.

npm test
npm run verify
npm run build:demo

Build or check one manifest:

node cli.mjs check --manifest fixtures/complete/manifest.json
node cli.mjs build --manifest fixtures/complete/manifest.json

Compare two snapshots:

node cli.mjs diff --before path/to/snapshot-a --after path/to/snapshot-b

The complete synthetic fixture models production, protected staging, rollback, backup and rollback runbooks, all three authority modes, resolved time evolution, measurement windows, and five independent gates.

Output

Each successful build creates:

generated/<project>/
  LATEST.json
  snapshots/<cutoff>_<semantic-hash>/
    project_os.json
    source_ledger.jsonl
    evidence_ledger.jsonl
    gates.json
    measurement_epochs.json
    validation.json
    diff.json
    PROJECT_OS.md
    EVIDENCE_LEDGER.md
    GATES_AND_MEASUREMENT.md
    RISK_AND_AUTHORITY.md
    NEXT_AGENT.md
    EXECUTIVE_REPORT.html

The Builder writes into a temporary directory first. An interrupted build is not promoted. Rebuilding the same semantic input checks determinism and rejects modified immutable snapshots.

See the committed synthetic executive report and Project OS snapshot.

Readiness is evidence, not optimism

• READY_FOR_HANDOFF: declared evidence gates passed for the modeled scope.
• REQUIRES_REVIEW: the package was built, but non-green gates, conflicts, risks, or missing evidence block handoff.
• BLOCKED: invalid input or a safety violation prevented snapshot promotion.

The public fixtures demonstrate both the positive and negative paths.

Safety

The validator rejects:

• absolute evidence paths;
• parent traversal and symlink/junction escape;
• .env, credentials, private keys, raw logs, and SQL backup paths;
• secret-like manifest values;
• string ratios such as "40/40";
• unknown source, denominator, epoch, and lineage references;
• critical current claims backed only by governance summaries;
• public outcome claims without fixed measurement epochs.

Run:

npm run public:scan

Real client/project manifests and raw evidence are intentionally absent from this repository.

Architecture

flowchart LR
    A["Expert-curated manifest"] --> B["Source hashing and safety gates"]
    B --> C["Stable claims and scoped gates"]
    C --> D["Immutable Project OS snapshot"]
    D --> E["Executive handoff"]
    D --> F["Semantic diff"]
    E --> G["Human approval boundary"]

Loading

Design-partner pilot

The current commercial hypothesis is a fixed-scope, service-led pilot for one site/business unit, one production environment, one staging/control lane, and one rollback/history lane.

The price and time-saving claims remain hypotheses until a real paid delivery and timed independent handoff are recorded.

Documentation

• Manifest contract
• Product scope and acceptance
• Reference-case method
• Security policy
• Changelog

License

Public source does not mean open source. No open-source license is granted in this design-partner release. See LICENSE.