Project Knowledge
Bundle OKF 0.1 · 0 conceitos · lennertvhoy/ProjectState_Template
Open source Repository Open in the app JSON README (API)
About
# Project Knowledge
This optional OKF bundle contains durable domain knowledge. ProjectState operational
truth remains authoritative for project status, active work, backlog, evidence,
delivery boundaries, and acceptance.
The bundle targets OKF v0.1 at specification commit
`ee67a5ca27044ebe7c38385f5b6cffc2305a9c1a`. Add project-owned concepts as
Markdown files with non-empty `type` frontmatter. Use the `projectstate` namespace
for `canonical`, `derived`, or `reference` authority and its provenance fields.
## Contents
No project concepts have been added by the template. This scaffold is
project-owned after explicit installation of the optional `knowledge_okf` module.
Details
- Kind
- OKF bundles
- Topic
- Developer tools
- Publisher
- lennertvhoy
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Stars
- 1
- Last push
- 2026-09-05T08:23:58Z
- Repository state
- ativo
- Language
- Python
- License
- NOASSERTION
- Added
- 2026-09-08 16:04:09
- Updated
- 2026-09-08 16:04:09
- Origin id
lennertvhoy/ProjectState_Template:knowledge/index.md
README
# ProjectState Template ProjectState is a small, repo-based workflow for keeping coding agents aligned with a real product outcome. Current template version: `projectstate-template-v6` The default is deliberately narrow: one human-owned project definition, one current slice, one primary user journey, and one bounded evidence summary. A failed user journey always outranks passing secondary checks. ## Start Create a new project: ```bash python3 scripts/init_template.py new --name "Your Project" --target ../your-project ``` Adopt an existing repository without replacing its README: ```bash python3 scripts/init_template.py adopt --name "Your Project" --target ../your-project --dry-run python3 scripts/init_template.py adopt --name "Your Project" --target ../your-project ``` Both commands use the `core` profile unless you explicitly choose another one. ## The core | Path | Sole responsibility | | --- | --- | | `PROJECT.md` | Human-owned user, outcome, scope, non-goals, and durable constraints | | `STATE.yaml` | One current slice, its acceptance, journey, blockers, risks, and exact next action | | `AGENTS.md` | Authority boundaries, workflow, stop-lines, and closure rules | | `evidence/<slice-id>/summary.md` | Commands, environment, results, artifacts, and unresolved limitations | The generated core also contains `scripts/projectstate_gate.py`, a small dependency-free checker. It checks recorded contract and evidence consistency, with the primary journey dominant. `README.md` remains product documentation, not a second state surface. The first gate run is expected to fail. A scaffold cannot honestly know the project's user, outcome, or real journey: ```bash python3 scripts/projectstate_gate.py ``` Confirm `PROJECT.md`, replace the placeholders in `STATE.yaml`, run the real journey yourself, record the result, and rerun the gate. ## What “green” means - `implemented`: the change exists. - `validated`: the named primary journey passed in the named environment. - remote/CI/deployed: separately proven only when acceptance crosses that boundary. - `accepted`: the human accepted the product result. Unit tests, repository validators, hashes, clean Git status, or complete metadata cannot turn a failed, blocked, or unrun primary journey green. Secondary checks may add blockers; they never reverse the primary result. The gate reads recorded state and evidence. It never executes a command merely because repository text contains one. Exit codes are: | Code | Meaning | | --- | --- | | `0` | `RECORDED OUTCOME VALIDATED`: recorded evidence supports validation with no recorded blockers | | `1` | `OUTCOME NOT VALIDATED`: honest unfinished work, unresolved placeholders, or a blocking finding | | `2` | `INVALID PROJECTSTATE CORE`: malformed, unsafe, or contradictory records | The gate rejects recognizable `Not yet defined`, `TODO`, and `TBD` placeholders in the contract and journey. It cannot judge whether arbitrary prose defines a good product, verify that a command actually ran, authenticate a human approval, or enforce checks described only in `HARDENED_POLICY.md`. Those require real observation and human review; record applicable check failures as blockers. When installation is in scope, test the distributed artifact in the intended clean environment. Source tests and a prepared development machine do not prove that package contents, launchers, or installation work. Keep publication and rehearsal results in supporting evidence; the primary journey retains its actual `not_run`, `passed`, `failed`, or `blocked` status. ## Human-owned governance The human owns the project outcome, non-goals, acceptance criteria, governance, risk exceptions, and product acceptance. Agents may update observed status, evidence, blockers, risks, and the next action. They may propose a governance change, but cannot approve or apply one simply to make their own work pass. This deliberately removes companion control commits, mutable commit-head bindings, line budgets, correction counters, and runtime dependence on workflow files from the default model. ## Two-strike simplification After two evidenced failures at the same delivery boundary, stop extending the mechanism. Record: - the assumption being reconsidered; - one moving part removed or bypassed; - the smallest real journey to rerun. The outcome gate blocks further closure until that review exists. This is based on two concrete failure records, not a general-purpose correction counter. ## Risk handling The core fails closed for unresolved data-loss, destructive-operation, privilege-escalation, secrets/private-data exposure, and permission-boundary risk. Critical or high findings with `reachable` or `unknown` exposure block regardless of category spelling. Category labels cannot bypass that stop-line. Other findings are assessed by severity, exposure, consequence, and affected environment. A vulnerability confined to build tooling or a demonstrably unreachable component is recorded with an owner and decision; it does not automatically outweigh a working product journey. Temporary acceptance needs a named human approver, rationale, and unexpired date. ## Profiles ### `core` — default Use for ordinary product work. It installs the four canonical artifacts and the outcome gate. Backlogs, worklogs, ADRs, release ledgers, multi-agent matrices, and compliance records are optional project choices. ```bash python3 scripts/init_template.py new --name "Your Project" --profile core ``` ### `hardened` — explicit opt-in Use only when actual exposure, regulation, or delivery obligations justify the additional policy. It adds `HARDENED_POLICY.md`; hardened checks may add blockers but cannot override the primary journey. ```bash python3 scripts/init_template.py new --name "Your Project" --profile hardened ``` ### v5 compatibility profiles `minimal`, `solo`, `team`, and `regulated` remain explicitly selectable during migration. They preserve the earlier multi-file and remote-closure workflows for existing consumers. They are not recommended for new projects and are never selected implicitly. ## Runtime independence ProjectState coordinates work only. Product code must not import, parse, or require `PROJECT.md`, `STATE.yaml`, `AGENTS.md`, `evidence/`, or its helper script to start or run. Deleting the coordination layer must not break the application. ## Optional material Add these only when the project needs them: - `BACKLOG.md` for a real multi-slice roadmap; - ADRs for durable architectural decisions; - threat models for meaningful attack surfaces; - remote CI/review proof when delivery is in scope; - signing, audit retention, or compliance evidence when obligations require it; - multi-agent ownership rules when agents actually run concurrently. The initializer refuses automatic optional asset-set expansion for the v6 profiles; add justified project-specific tooling in a separately reviewed change. Git history is the default work history. Do not duplicate it into a mandatory workflow ledger. ## Maintainer notes Start with the core files above, `scripts/init_template.py`, `scripts/projectstate_gate.py`, and `scripts/test_outcome_core.py`. [The worked example](docs/WORKED_EXAMPLE.md) runs a packaged product through failure, a handoff read by a new process, recovery, and restart. The design decision and migration boundary are recorded in `docs/adr/0003-outcome-first-core.md`. The template repository retains the v5 implementation and historical files as compatibility material, but its current authority is `AGENTS.md`, `PROJECT.md`, and `STATE.yaml`. Run the focused core journey: ```bash python3 scripts/test_outcome_core.py ``` Also run relevant legacy compatibility tests before publishing a migration. A local pass is not remote delivery, CI verification, release, or human acceptance.