From 81c686b1c3368ddd06e933d4bf5b0b2fbffd0fca Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Mon, 3 Aug 2026 04:31:39 +0100 Subject: [PATCH] docs: close remaining current-state drift --- .agent-loop/README.md | 5 ++-- .../policies/repository-engineering-policy.md | 9 ++------ AGENTS.md | 12 +++++----- CONTRIBUTING.md | 23 +++++++------------ README.md | 10 ++++---- docs/decision_0001_core_scope.md | 2 +- ...sion_0002_db_first_not_blockchain_first.md | 2 +- docs/roadmap_status.md | 14 +++++------ 8 files changed, 33 insertions(+), 44 deletions(-) diff --git a/.agent-loop/README.md b/.agent-loop/README.md index 8347e48c1..0c511bee4 100644 --- a/.agent-loop/README.md +++ b/.agent-loop/README.md @@ -4,9 +4,8 @@ This directory stores durable planning and review context for Workstream. It is not product state and it is not an authorization database. Useful records include initiative intent, plans, bounded chunk contracts, -risks, decisions, evidence, and review notes. Historical signed-loop and -recovery artifacts remain only where they help explain earlier decisions; they -do not activate work, lock initiatives, or block pull requests. +risks, decisions, evidence, and review notes. Historical records remain only +where they help explain earlier decisions. The active engineering loop is: diff --git a/.agent-loop/policies/repository-engineering-policy.md b/.agent-loop/policies/repository-engineering-policy.md index 45ac2c503..558961a5b 100644 --- a/.agent-loop/policies/repository-engineering-policy.md +++ b/.agent-loop/policies/repository-engineering-policy.md @@ -11,12 +11,8 @@ ## Contribution Authority GitHub repository permissions and branch protection govern contribution -authority. Plans, contracts, review evidence, and `.agent-loop/` records are -useful engineering context, not runtime authorization. - -The repository does not require signed starts, active-chunk leases, -administrator dispatches, merge intents, recovery certificates, or generated -loop memory before implementation or pull-request creation. +authority. Plans, contracts, review evidence, and `.agent-loop/` records +preserve engineering context and rationale. ## Engineering Loop @@ -31,7 +27,6 @@ Intent -> Plan -> Bounded Change -> Tests -> Review -> PR -> Human Merge architecture, workflow, or product-lifecycle changes. - Different initiatives may proceed concurrently. - Explicit human approval is required before merge. -- Derived process records must never block product development. ## Core Boundaries diff --git a/AGENTS.md b/AGENTS.md index e05a3a4a3..ed26da268 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,12 +21,9 @@ Workstream is how Flow measures, certifies, and coordinates useful human-agent w - Durable engineering memory, initiative plans, chunk contracts, policies, evidence, and review logs live under `.agent-loop/`. - `CONTRIBUTING.md` is the canonical human and agent entry path. GitHub permissions and branch protection govern contribution authority. Planning - artifacts explain work; they do not activate, lease, or lock it. -- Do not require signed starts, explicit-event dispatches, active-chunk state, - merge intents, recovery certificates, or generated loop memory to implement - work or open a pull request. + artifacts explain work; they do not authorize or block it. - Distinct initiatives may proceed concurrently in separate branches or - worktrees. Derived process state must never block product development. + worktrees. - Do not add Claude-specific files unless the user explicitly asks for cross-tool support. - Do not use old names such as "task-production control plane" or "Garden roadmap". - Spreadsheet exports live locally under ignored `sheets/`; do not commit them. @@ -42,7 +39,10 @@ Workstream is how Flow measures, certifies, and coordinates useful human-agent w specifications remain normative. Do not use dates, weeks, or delivery windows as implementation authority. - For workflow states, persisted tokens, API enum values, roles, and lifecycle names, prefer subsystem- or actor-specific names over vague labels. If the naming has product or security impact and the user is unavailable, run the required internal reviewer tracks before locking it. -- Keep v0.1 focused on project guide -> task -> submission -> checks -> review -> revision -> contribution records -> conditional compensation awards/fulfillment -> reputation signals. +- Keep v0.1 focused on project guide -> task -> submission -> checks -> review + -> revision -> contribution records -> conditional compensation + awards/fulfillment -> contribution evidence for a future reputation + projection. Runtime reputation projection remains deferred. - Review decision stored values are only accept, needs_revision, or reject. - Frontend is locked as React + Vite + TypeScript. - Backend API is locked as Python with FastAPI. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9b0697186..947377dbc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,7 +21,7 @@ runtime locks. Before implementation, update from current `main` and read: 1. [README.md](README.md) for the product boundary and current v0.1 summary. -2. [Current v0.1 Status](docs/roadmap_status.md) for implemented, active, and +2. [Current v0.1 Status](docs/roadmap_status.md) for implemented, in-progress, and remaining capabilities. 3. [Architecture Lockdown](docs/architecture_lockdown.md), accepted ADRs, and the canonical specification for the subsystem being changed. @@ -38,9 +38,8 @@ not introduce delivery promises such as day plans, numbered weeks, or rolling time windows as repository authority. Contributors with GitHub write access may create a branch, implement a bounded -change, and open a pull request without a signed start event, administrator -dispatch, active-chunk lease, or loop-memory approval. Contributors without -write access may use a fork and open a normal pull request. +change, and open a pull request. Contributors without write access may use a +fork and open a normal pull request. ## Before Opening A Pull Request @@ -58,10 +57,9 @@ to contribute. ## Review And Merge -GitHub CI validates repository quality. It does not consult signed loop memory -or require a merge-intent file. CodeRabbit and internal agents supplement human -review. A maintainer must explicitly approve the final pull request before it -is merged. +GitHub CI validates repository quality. CodeRabbit and internal agents +supplement human review. A maintainer must explicitly approve the final pull +request before it is merged. Different initiatives may proceed concurrently in separate branches or worktrees. If another pull request changes the base, inspect the new delta and @@ -70,10 +68,5 @@ rerun affected checks; unchanged evidence does not need ceremonial repetition. ## Durable Records Keep useful plans, contracts, review notes, and historical `.agent-loop/` -artifacts. They explain decisions but do not activate work or block pull -requests. Git and GitHub are the source of truth for commits, reviews, checks, -and merges. - -The former signed-start, explicit-event, recovery-certificate, and generated -loop-memory runtimes were removed because derived process state must never -deadlock contribution or require self-authorizing recovery. +artifacts. They explain decisions and preserve evidence. Git and GitHub are the +source of truth for commits, reviews, checks, and merges. diff --git a/README.md b/README.md index effe255f9..69f9859f9 100644 --- a/README.md +++ b/README.md @@ -70,12 +70,14 @@ Implemented foundations on `main` include external Flow-token verification, canonical local actors and authorization, project guides and task records, submission packets, immutable artifact storage, automated checker execution, and the pre-review gate. Project-guide ingestion now has typed source handling, -bounded extraction, security controls, and persisted sufficiency evidence. +bounded extraction, security controls, persisted sufficiency evidence, and +authorized fixed-service guide-source binding and reads. Active work is connecting those foundations into the remaining production -lifecycle: authoritative guide binding and reads, review and revision, -contribution records, conditional compensation awards and fulfillment, and -reputation projections. Frontend product work follows stable and tested backend +lifecycle: the remaining artifact custody chain, review and revision, +contribution records, and conditional compensation awards and fulfillment. +Contribution evidence remains the input for a separately implemented future +reputation projection. Frontend product work follows stable and tested backend contracts for the surface it consumes. The release bar is a verified end-to-end v0.1 lifecycle, not the completion of diff --git a/docs/decision_0001_core_scope.md b/docs/decision_0001_core_scope.md index 994f9b30e..9b1aee830 100644 --- a/docs/decision_0001_core_scope.md +++ b/docs/decision_0001_core_scope.md @@ -2,7 +2,7 @@ ## Status -Accepted for 30-day build. +Accepted for v0.1. ## Decision diff --git a/docs/decision_0002_db_first_not_blockchain_first.md b/docs/decision_0002_db_first_not_blockchain_first.md index 2c7a80fe9..9ddba3250 100644 --- a/docs/decision_0002_db_first_not_blockchain_first.md +++ b/docs/decision_0002_db_first_not_blockchain_first.md @@ -23,7 +23,7 @@ fulfillment. Positive: -- simpler 30-day build +- simpler v0.1 delivery - easier manual reconciliation - faster pilot - avoids premature protocol coupling diff --git a/docs/roadmap_status.md b/docs/roadmap_status.md index 715c4834a..dbd6908e9 100644 --- a/docs/roadmap_status.md +++ b/docs/roadmap_status.md @@ -49,8 +49,8 @@ remain outside v0.1. administrator grants, fixed-service identities, and runtime admission. - Project-role grants, administrative APIs, authority evidence, idempotency, and PostgreSQL-backed rate controls. -- Project setup and project mutation/read authorization foundations used by the - current guide integration work. +- Project setup plus project create, guide mutation, binding, and read + authorization foundations. ### Project, task, submission, and checker foundations @@ -71,15 +71,14 @@ remain outside v0.1. controls. - Image metadata handling and persisted guide-sufficiency evidence. - Guide materialization from persisted artifact-processing evidence. +- Fixed-service guide-source reads and binding creation with authorization, + custody, lineage, rate-control, and stale-generation enforcement. ## Integration In Progress The following areas have merged planning, contracts, or partial foundations, but are not all complete as one production path: -- authoritative project-guide binding and read activation across ART and AUTH; -- reviewed cross-initiative contracts connecting artifact custody with - authorization-owned project guide reads; - review-policy persistence and activation across REV and AUTH; - review queue, reviewer assignment/claim, immutable decisions, and revision replay on the canonical authorization boundary; @@ -90,8 +89,9 @@ review. Their presence does not change the implemented-on-`main` list above. ## Remaining v0.1 Capability Milestones -1. Complete the production guide binding/read path and prove its authorization, - custody, lineage, and stale-generation behavior. +1. Complete the remaining artifact custody chain: contributor intake cleanup, + archive safety, semantic change gating, durable admission, submission + binding, checker/review materialization, recovery, and provider proof. 2. Complete review and revision persistence, queueing, access, decisions, findings, replay, and operational recovery. 3. Create immutable contributor and reviewer contribution records from the