Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# Chunk Map

| Chunk | Purpose | State |
| --- | --- | --- |
| `WS-DOCS-001-01` | Modernize the current v0.1 documentation entry path and archive expired calendar framing | In progress |

This initiative intentionally uses one documentation-only chunk. Splitting the
entry pages would allow contradictory wording to remain between merges.
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Decisions

## Capability-Based Status

Current status uses Implemented, In progress, Planned, and Historical
capability categories. It does not use weeks, days, or completion promises.

## Preserve History

Superseded calendar plans and early chunk records remain in place for audit and
design history. Clear notices and a historical index prevent them from being
mistaken for current authority.

## One Current Entry Path

`README.md` summarizes the product and v0.1 state, `docs/roadmap_status.md` owns
the detailed capability ledger, `CONTRIBUTING.md` owns the contributor path,
and `AGENTS.md` adds repository-specific agent rules. Other documents link to
these owners instead of duplicating current status.
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# Discovery

## Findings

- `README.md` presents expired day/week plans and early chunk specifications as
the active planning package.
- `docs/roadmap_status.md` is an early chronological log, not a reliable view of
current `main`.
- `AGENTS.md` retains a Week 1 implementation rule even though the underlying
backend-contract-first constraint remains valid without a calendar label.
- `CONTRIBUTING.md` correctly uses the simple engineering loop but does not
explain which documents are current authority and which are history.
- Architecture and diagram entry pages use "first 30 days" for the current
v0.1 boundary.
- Historical plans and trial records remain useful evidence and should be
preserved with explicit archive notices.

## Sources Of Truth

- Product definition: `README.md`, `docs/glossary.md`.
- Architecture boundary: `docs/architecture_lockdown.md` and accepted ADRs.
- Implemented behavior: code, migrations, tests, and merged commits on `main`.
- Work in progress: open pull requests and their reviewed contracts.
- History: imported files under `docs/reference_specs/` unless explicitly
adopted by a current document, closed initiative records, internal reviews,
and superseded calendar plans.
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# WS-DOCS-001: Current v0.1 Documentation

## Intent

Make the repository entry path describe Workstream's current v0.1 product,
architecture, implementation state, and contribution workflow without using an
expired calendar as the roadmap.

## Why Now

The root README still presents a 30-day plan, week plans, and early chunk
specifications as the primary planning package. `docs/roadmap_status.md` still
describes the authorization foundation as the current phase even though later
authorization, artifact, project-guide, and cross-initiative work has merged.
That makes current capability, historical implementation evidence, and future
work difficult to distinguish.

## Non-Goals

- No runtime, API, schema, migration, workflow, or CI behavior changes.
- No deletion or rewriting of immutable reference specifications, internal
review evidence, or initiative history.
- No promise of release dates or completion dates.
- No claim that a planned or draft capability is available.

## Success

A new contributor can start with `README.md`, `AGENTS.md`, and
`CONTRIBUTING.md`, understand the v0.1 boundary, locate current status, tell
current guidance from history, and contribute through the simple engineering
loop.
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Plan

1. Replace the README planning package with a current v0.1 entry path and a
capability-based status summary.
2. Rewrite roadmap status around implemented, in-progress, and remaining
capability milestones.
3. Make `AGENTS.md` and `CONTRIBUTING.md` explicitly route contributors to
current authority and preserve the simple engineering loop.
4. Remove calendar framing from current architecture and diagram entry pages.
5. Label superseded calendar plans and early chunk/trial records as historical
without rewriting their evidence.
6. Run stale-wording, link, and documentation consistency checks, followed by
proportionate internal review.
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# Internal Review

## Documentation

Pass. No missing documentation, navigation, historical-labeling, or link
findings.

## Product and Operations

Initial findings removed the remaining day-based success metric and corrected
reputation wording so v0.1 preserves authoritative contribution evidence while
runtime reputation projection remains deferred. Re-review passed.

## Architecture

Initial low-risk findings removed calendar framing from the product brief and
moved reviewed cross-initiative contracts out of the implemented-capability
list. Re-review passed with no architecture drift.

## Senior Engineering

The generated PDF was added explicitly to scope, imported reference inputs were
distinguished from canonical repository specifications, and PDF regeneration
provenance was recorded. Re-review passed. The former schema-v1
`chunk-scope-json` mechanism was not restored because current repository policy
explicitly retired that runtime and does not require it for pull requests.
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# Risks

| Risk | Mitigation |
| --- | --- |
| Documentation claims planned behavior is implemented | Classify capabilities as implemented, in progress, planned, or historical; require merged-code evidence for implemented claims. |
| Current status becomes another chronological log | Organize by durable capability milestones and update the ledger when capability boundaries change. |
| Historical evidence is lost | Preserve old plans and implementation records behind an explicit historical index. |
| Entry pages contradict canonical contracts | Keep terminology aligned with the glossary, architecture lockdown, accepted ADRs, and stale-contract scanners. |
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# Status

`WS-DOCS-001-01` is locally complete and ready for pull-request review.

The entry-path rewrite is complete locally. Deterministic documentation checks
pass, and all valid internal review findings have been resolved. Merge remains
a human decision after GitHub checks and external review.
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# WS-DOCS-001-01: Current v0.1 Entry Path

## Scope

Update repository-facing product, contributor, status, architecture-navigation,
and historical-plan documentation so current guidance is capability-based.

## Allowed Files

- `README.md`
- `AGENTS.md`
- `CONTRIBUTING.md`
- `docs/roadmap_status.md`
- `docs/historical_planning.md`
- `docs/architecture_brief/workstream_architecture_brief.pdf`, as the generated
companion to its changed Markdown source
- existing calendar-plan, early checker/chunk, architecture, product, reviewer,
and diagram Markdown documents touched only to remove current calendar
framing or add a historical notice
- this initiative directory

## Not Allowed

- backend or frontend code
- tests, migrations, workflows, or package configuration
- immutable files below `docs/reference_specs/` or `docs/internal_reviews/`
- product behavior changes

## Acceptance Criteria

- Root entry pages contain no Week 1/Week 2/30-day roadmap framing.
- Current status is organized by capability and does not overclaim draft work.
- Historical plans remain accessible but cannot be mistaken for current
sequencing or authority.
- Contribution guidance clearly identifies present sources of truth.
- Markdown links and repository stale-wording checks pass.

## Risk

L2 documentation risk: broad discoverability impact, no runtime change.

## Verification

- `python3 scripts/check_markdown_links.py`
- `python3 scripts/check_stale_workstream_wording.py`
- `python3 scripts/check_stale_authorization_docs.py`
- `python3 scripts/check_stale_artifact_contracts.py`
- `git diff --check`

The architecture PDF is regenerated from its changed Markdown source with the
Pandoc/WeasyPrint command documented in
`docs/architecture_brief/render_pdf.sh`. Diagram assets are unchanged.

## Reviewers

- documentation
- product/operations
- architecture
- senior engineering
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# WS-DOCS-001-01 External Review Response

## Comments Addressed

1. Aligned the decision record with the capability ledger's exact
`Implemented`, `In progress`, `Planned`, and `Historical` labels.
2. Removed the historical checker trial's claim that it proves current backend
behavior and routed current claims to the capability ledger and merged
evidence.
3. Named the Workstream product lifecycle explicitly in the backend component
diagram text so it cannot be confused with the engineering loop.
4. Routed readers of the historical planning index through `CONTRIBUTING.md`.
5. Clarified that v0.1 preserves contribution evidence for a future reputation
projection; runtime reputation projection remains deferred.
6. Reworded the residual historical-document risk as mitigation rather than an
absolute guarantee that archive notices prevent misuse.

## Comments Deferred

None.

## Human Decisions Needed

None.

## Commands Rerun

- `python3 scripts/check_markdown_links.py`
- `python3 scripts/check_stale_workstream_wording.py`
- `python3 scripts/check_stale_authorization_docs.py`
- `python3 scripts/check_stale_artifact_contracts.py`
- `git diff --check`

## Remaining Risks

Historical checker records intentionally retain their original scenario and
result vocabulary. Their archive notice and current-evidence link reduce the
risk that they are used as current implementation authority.
10 changes: 9 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,14 +35,22 @@ Workstream is how Flow measures, certifies, and coordinates useful human-agent w
- If updating the roadmap, update both local XLSX and CSV exports.
- Do not import XLSX into Google Sheets with "replace spreadsheet"; use a temporary sheet and copy only the roadmap tab.
- Prefer evidence-backed docs over vague product claims.
- Treat `docs/roadmap_status.md` as the current capability ledger. Calendar
plans, early chunk specifications, imported files under
`docs/reference_specs/`, and internal reviews are historical evidence unless
a current entry page explicitly adopts them. Canonical repository
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.
- 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.
- ORM, migrations, and API schemas are locked as SQLAlchemy 2.x async + Alembic + Pydantic schemas.
- Workstream verifies external Flow authentication tokens; do not add Workstream-owned login, signup, password reset, password storage, or primary auth sessions.
- Week 1 implementation is backend-first; do not start frontend work until backend contracts and lifecycle guards are stable.
- v0.1 delivery is backend-contract-first. Do not add frontend behavior until
the backing API contracts and lifecycle guards for that surface are stable
and tested.
- Execution is async-first; do not document synchronous-first checkers or jobs.
- FastAPI background tasks are acceptable for simple local v0.1 jobs; use Celery or equivalent durable workers when retries, scheduling, isolation, or distributed execution are needed.
- Postgres is the record database.
Expand Down
21 changes: 21 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,27 @@ or higher-risk work, add a short initiative plan and chunk contract under
`.agent-loop/initiatives/`. Existing planning artifacts are useful context, not
runtime locks.

## Find The Current Contract

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
remaining capabilities.
3. [Architecture Lockdown](docs/architecture_lockdown.md), accepted ADRs, and
the canonical specification for the subsystem being changed.

Code, migrations, tests, accepted ADRs, and canonical repository specifications
define implemented or required behavior. Open pull requests describe work in
progress. Calendar plans, early chunk specifications, imported files under
`docs/reference_specs/`, internal review records, and closed initiative records
are useful history unless a current document explicitly adopts them; they are
not by themselves current sequencing or proof that behavior is live.

Roadmaps and status documents must use capability milestones and evidence. Do
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
Expand Down
53 changes: 37 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,22 +61,40 @@ Different projects speak different domain languages, but serious task evaluation

Workstream turns that operating knowledge into reusable infrastructure.

## Planning Package
## Current v0.1 State

Workstream is under active v0.1 development. Progress is tracked by proven
capabilities, not by calendar weeks or promised dates.

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.

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
contracts for the surface it consumes.

The release bar is a verified end-to-end v0.1 lifecycle, not the completion of
an old timeboxed plan. See [Current v0.1 Status](docs/roadmap_status.md) for the
capability ledger and explicit remaining work.

## Start Here

- [Contribution Guide](CONTRIBUTING.md)
- [Codex Agent Loop](.agent-loop/README.md)
- [Repository Engineering Policy](.agent-loop/policies/repository-engineering-policy.md)
- [30-Day Master Plan](docs/roadmap_30_day_master_plan.md)
- [Roadmap Status](docs/roadmap_status.md)
- [Week 1 Backend Plan](docs/roadmap_week1_backend_plan.md)
- [Week 2 Checker Framework Specification](docs/spec_week2_checker_framework.md)
- [Chunk 6 Checker Contract And Records](docs/spec_chunk_6_checker_contract_records.md)
- [Chunk 7 Checker Runner And Registry](docs/spec_chunk_7_checker_runner_registry.md)
- [Chunk 8 Submission Artifact And Policy Checkers](docs/spec_chunk_8_submission_artifact_policy_checkers.md)
- [Chunk 9 Pre-Review Gate](docs/spec_chunk_9_pre_review_gate.md)
- [Chunk 10 Checker Trial](docs/spec_chunk_10_checker_trial.md)
- [Day-by-Day Execution Plan](docs/roadmap_day_by_day_execution_plan.md)
- [Implementation Backlog](docs/roadmap_implementation_backlog.md)
- [Current v0.1 Status](docs/roadmap_status.md)
- [Product Principles](docs/product_principles.md)
- [Product Brief](docs/product_brief.md)
- [Architecture Lockdown](docs/architecture_lockdown.md)
- [System Architecture](docs/architecture_system_architecture.md)
- [Glossary](docs/glossary.md)
- [Historical Planning Index](docs/historical_planning.md)

## Product And Operations Documentation

- [Product Principles](docs/product_principles.md)
- [Product Brief](docs/product_brief.md)
- [First User Flows](docs/product_first_user_flows.md)
Expand All @@ -101,10 +119,13 @@ Workstream turns that operating knowledge into reusable infrastructure.
- [Compensation And Reputation](docs/operations_payment_reputation.md)
- [Risk Register](docs/risk_register.md)
- [Process Pattern Baseline](docs/process_pattern_baseline.md)
- [Architecture Lockdown](docs/architecture_lockdown.md)
- [Glossary](docs/glossary.md)

## Review Passes
## Historical Review Records

These records preserve earlier product, architecture, process, and adversarial
reviews. They are evidence and design history, not current implementation
status. Current changes receive review through [CONTRIBUTING.md](CONTRIBUTING.md).

- [Process Baseline Operations Review](docs/review_process_baseline_operations_review.md)
- [Final Product Strategy Review](docs/review_final_product_strategy_review.md)
Expand Down
Loading
Loading