{
  "markdown": "# ProjectState Template\n\nProjectState is a small, repo-based workflow for keeping coding agents aligned\nwith a real product outcome.\n\nCurrent template version: `projectstate-template-v6`\n\nThe default is deliberately narrow: one human-owned project definition, one\ncurrent slice, one primary user journey, and one bounded evidence summary. A\nfailed user journey always outranks passing secondary checks.\n\n## Start\n\nCreate a new project:\n\n```bash\npython3 scripts/init_template.py new --name \"Your Project\" --target ../your-project\n```\n\nAdopt an existing repository without replacing its README:\n\n```bash\npython3 scripts/init_template.py adopt --name \"Your Project\" --target ../your-project --dry-run\npython3 scripts/init_template.py adopt --name \"Your Project\" --target ../your-project\n```\n\nBoth commands use the `core` profile unless you explicitly choose another one.\n\n## The core\n\n| Path | Sole responsibility |\n| --- | --- |\n| `PROJECT.md` | Human-owned user, outcome, scope, non-goals, and durable constraints |\n| `STATE.yaml` | One current slice, its acceptance, journey, blockers, risks, and exact next action |\n| `AGENTS.md` | Authority boundaries, workflow, stop-lines, and closure rules |\n| `evidence/<slice-id>/summary.md` | Commands, environment, results, artifacts, and unresolved limitations |\n\nThe generated core also contains `scripts/projectstate_gate.py`, a small\ndependency-free checker. It checks recorded contract and evidence consistency,\nwith the primary journey dominant. `README.md` remains product documentation, not a\nsecond state surface.\n\nThe first gate run is expected to fail. A scaffold cannot honestly know the\nproject's user, outcome, or real journey:\n\n```bash\npython3 scripts/projectstate_gate.py\n```\n\nConfirm `PROJECT.md`, replace the placeholders in `STATE.yaml`, run the real\njourney yourself, record the result, and rerun the gate.\n\n## What “green” means\n\n- `implemented`: the change exists.\n- `validated`: the named primary journey passed in the named environment.\n- remote/CI/deployed: separately proven only when acceptance crosses that boundary.\n- `accepted`: the human accepted the product result.\n\nUnit tests, repository validators, hashes, clean Git status, or complete metadata\ncannot turn a failed, blocked, or unrun primary journey green. Secondary checks\nmay add blockers; they never reverse the primary result.\n\nThe gate reads recorded state and evidence. It never executes a command merely\nbecause repository text contains one. Exit codes are:\n\n| Code | Meaning |\n| --- | --- |\n| `0` | `RECORDED OUTCOME VALIDATED`: recorded evidence supports validation with no recorded blockers |\n| `1` | `OUTCOME NOT VALIDATED`: honest unfinished work, unresolved placeholders, or a blocking finding |\n| `2` | `INVALID PROJECTSTATE CORE`: malformed, unsafe, or contradictory records |\n\nThe gate rejects recognizable `Not yet defined`, `TODO`, and `TBD` placeholders\nin the contract and journey. It cannot judge whether arbitrary prose defines a\ngood product, verify that a command actually ran, authenticate a human approval,\nor enforce checks described only in `HARDENED_POLICY.md`. Those require real\nobservation and human review; record applicable check failures as blockers.\n\nWhen installation is in scope, test the distributed artifact in the intended\nclean environment. Source tests and a prepared development machine do not prove\nthat package contents, launchers, or installation work. Keep publication and\nrehearsal results in supporting evidence; the primary journey retains its actual\n`not_run`, `passed`, `failed`, or `blocked` status.\n\n## Human-owned governance\n\nThe human owns the project outcome, non-goals, acceptance criteria, governance,\nrisk exceptions, and product acceptance. Agents may update observed status,\nevidence, blockers, risks, and the next action. They may propose a governance\nchange, but cannot approve or apply one simply to make their own work pass.\n\nThis deliberately removes companion control commits, mutable commit-head\nbindings, line budgets, correction counters, and runtime dependence on workflow\nfiles from the default model.\n\n## Two-strike simplification\n\nAfter two evidenced failures at the same delivery boundary, stop extending the\nmechanism. Record:\n\n- the assumption being reconsidered;\n- one moving part removed or bypassed;\n- the smallest real journey to rerun.\n\nThe outcome gate blocks further closure until that review exists. This is based\non two concrete failure records, not a general-purpose correction counter.\n\n## Risk handling\n\nThe core fails closed for unresolved data-loss, destructive-operation,\nprivilege-escalation, secrets/private-data exposure, and permission-boundary\nrisk. Critical or high findings with `reachable` or `unknown` exposure block\nregardless of category spelling. Category labels cannot bypass that stop-line.\n\nOther findings are assessed by severity, exposure, consequence, and affected\nenvironment. A vulnerability confined to build tooling or a demonstrably\nunreachable component is recorded with an owner and decision; it does not\nautomatically outweigh a working product journey. Temporary acceptance needs a\nnamed human approver, rationale, and unexpired date.\n\n## Profiles\n\n### `core` — default\n\nUse for ordinary product work. It installs the four canonical artifacts and the\noutcome gate. Backlogs, worklogs, ADRs, release ledgers, multi-agent matrices,\nand compliance records are optional project choices.\n\n```bash\npython3 scripts/init_template.py new --name \"Your Project\" --profile core\n```\n\n### `hardened` — explicit opt-in\n\nUse only when actual exposure, regulation, or delivery obligations justify the\nadditional policy. It adds `HARDENED_POLICY.md`; hardened checks may add blockers\nbut cannot override the primary journey.\n\n```bash\npython3 scripts/init_template.py new --name \"Your Project\" --profile hardened\n```\n\n### v5 compatibility profiles\n\n`minimal`, `solo`, `team`, and `regulated` remain explicitly selectable during\nmigration. They preserve the earlier multi-file and remote-closure workflows for\nexisting consumers. They are not recommended for new projects and are never\nselected implicitly.\n\n## Runtime independence\n\nProjectState coordinates work only. Product code must not import, parse, or\nrequire `PROJECT.md`, `STATE.yaml`, `AGENTS.md`, `evidence/`, or its helper script\nto start or run. Deleting the coordination layer must not break the application.\n\n## Optional material\n\nAdd these only when the project needs them:\n\n- `BACKLOG.md` for a real multi-slice roadmap;\n- ADRs for durable architectural decisions;\n- threat models for meaningful attack surfaces;\n- remote CI/review proof when delivery is in scope;\n- signing, audit retention, or compliance evidence when obligations require it;\n- multi-agent ownership rules when agents actually run concurrently.\n\nThe initializer refuses automatic optional asset-set expansion for the v6\nprofiles; add justified project-specific tooling in a separately reviewed change.\n\nGit history is the default work history. Do not duplicate it into a mandatory\nworkflow ledger.\n\n## Maintainer notes\n\nStart with the core files above, `scripts/init_template.py`,\n`scripts/projectstate_gate.py`, and `scripts/test_outcome_core.py`.\n[The worked example](docs/WORKED_EXAMPLE.md) runs a packaged product through\nfailure, a handoff read by a new process, recovery, and restart.\n\nThe design decision and migration boundary are recorded in\n`docs/adr/0003-outcome-first-core.md`. The template repository retains the v5\nimplementation and historical files as compatibility material, but its current\nauthority is `AGENTS.md`, `PROJECT.md`, and `STATE.yaml`.\n\nRun the focused core journey:\n\n```bash\npython3 scripts/test_outcome_core.py\n```\n\nAlso run relevant legacy compatibility tests before publishing a migration. A\nlocal pass is not remote delivery, CI verification, release, or human acceptance.\n",
  "bytes": 7874,
  "sha": "096353d95314355b7fdb8a3ebb697abc8d4bd91c0182f8c385fcb79b1ea112bb",
  "repo_slug": "lennertvhoy/projectstate_template",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_lennertvhoy_projectstate_template_knowle_f5437d3f/readme"
}