From 6345efc1a547b625081a44aef120cd5afde156d7 Mon Sep 17 00:00:00 2001 From: AlbertXXuu <204706285+AlbertXXuu@users.noreply.github.com> Date: Sat, 26 Sep 2026 12:39:46 +0800 Subject: [PATCH] docs: clarify current engineering scope and preserve historical plans --- AGENTS.md | 8 ++++---- PLANS.md | 8 +++++++- PROJECT_CHARTER.md | 9 +++++++-- README.md | 9 +++++---- harness/build-log.md | 4 ++++ harness/context/README.md | 4 ++++ plans/00-repository-foundation.md | 4 ++++ plans/01-single-session-foundation-and-architecture.md | 4 ++++ plans/02-local-functional-regression-spike-a.md | 4 ++++ plans/03-brand-verifiable-demo.md | 4 ++++ plans/04-local-differential-verifier.md | 4 ++++ plans/05-demo-saved-run-readiness.md | 4 ++++ plans/06-drawdb-value-validation.md | 4 ++++ plans/07-public-alpha-readiness.md | 4 ++++ plans/README.md | 5 +++++ reference/ARCHITECTURE_AND_ACCEPTANCE_BASELINE.md | 4 ++++ 16 files changed, 72 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c04b104..c479466 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,9 +10,9 @@ Read `PROJECT_CHARTER.md` before making product or architecture decisions. This repository is for local functional QA and regression engineering. -- Work only on repositories and test applications supplied by the user. +- Work on existing repository fixtures, already authorized public cases, or repositories and test applications supplied by the user. Record the source and exact revisions used. - Run target applications locally on loopback addresses or in a disposable local test environment. -- Do not discover new public targets or broaden the task beyond the supplied repository. +- New target discovery must be part of the assigned task; keep engineering maintenance within its assigned repository and existing cases. - Do not access external accounts, production systems, private data, or third-party hosted instances. - Do not broaden the task beyond functional behavior in the supplied local test application. - If a requested task is not ordinary local functional QA, stop and report it as outside this workflow. @@ -35,14 +35,14 @@ This repository is for local functional QA and regression engineering. and one writer at a time. Add an exclusive worktree only for a concrete parallel need; follow `docs/foundation/branch-and-worktree-policy.md` for integration and cleanup. - Read only the files relevant to the assigned phase. -- For multi-step work, create or update an ExecPlan under `plans/`. +- For multi-step implementation needing durable coordination, create or update an ExecPlan under `plans/`; reuse the assigned phase record. Simple reversible documentation fixes do not require a new plan. - Record baseline commands and their actual results before editing. - Modify only the directories authorized by the phase prompt. - Preserve unrelated user work and all prior attempts. - Prefer small, reviewable commits. - Resolve routine ambiguity using the safest reversible option and record the decision. - Do not claim success without command output or inspectable artifacts. -- If required inputs are missing, return `blocked`; if an accepted check cannot observe one +- If required inputs are missing, continue independent assigned work and identify the dependent step; if an accepted check cannot observe one outcome, classify that outcome `inconclusive`; if a required Spike gate fails, the final Spike decision is `NO-GO`. Always include evidence. - Parallel branches update only their own phase context. The integration branch alone updates the central build log. diff --git a/PLANS.md b/PLANS.md index dac2c1a..996fb75 100644 --- a/PLANS.md +++ b/PLANS.md @@ -4,6 +4,9 @@ State the one observable user outcome this phase must produce. +Name the existing Issue, reproducible failure, explicit requirement or registered research hypothesis +that justifies the work, its evidence location, and the smallest acceptance condition. + ## Scope ### Allowed paths @@ -14,7 +17,10 @@ State the one observable user outcome this phase must produce. - ... -## Inputs supplied by the user +## Authorized inputs and existing fixtures + +Use existing fixtures or already authorized public cases when sufficient. Record unknown inputs +and resolve only the milestones that depend on them; external user recruitment is not a prerequisite. - target repository/path: - issue snapshot: diff --git a/PROJECT_CHARTER.md b/PROJECT_CHARTER.md index f722985..0388382 100644 --- a/PROJECT_CHARTER.md +++ b/PROJECT_CHARTER.md @@ -113,11 +113,16 @@ The source of truth is not a model statement or a screenshot alone. It is the co ### Production v0.x - fresh install works; -- local fixture and one user-selected real case both work; +- local fixtures and a documented authorized case both work, with pinned inputs and revisions; - replay has no model dependency; - package and GitHub Action have bounded, documented behavior; - an independent reviewer can reproduce the evidence. ### v1.0 -Do not plan v1.0 until at least one external maintainer keeps the generated test or CI integration in a real project and external feedback has changed the product contract. +Plan a stable release from a defined supported workflow, fresh-install and end-to-end validation, +versioned evidence compatibility, clear failure behavior, complete documentation, and a reviewed +maintenance scope. These are future acceptance requirements, not a declaration that v1.0 is ready. +External adoption remains an observed outcome and can inform later changes; it is not a prerequisite +for engineering improvements or release planning. Efficiency and production claims require their +own evidence. diff --git a/README.md b/README.md index ed8432e..7b9a48f 100644 --- a/README.md +++ b/README.md @@ -173,10 +173,11 @@ actual acceptance commands. Read the [project charter](PROJECT_CHARTER.md), ## Project gate -Public source and passing CI do not grant product `GO`. The next gate is one outside maintainer, -without author assistance, completing `init → review → check → run → verify`, keeping the standalone -test or CI integration, and providing feedback that changes the product contract. Until then, do -not claim automatic generation, saved developer time, lower maintenance cost or production support. +The next engineering milestone is a complete, documented `init → review → check → run → verify` +workflow using existing fixtures and authorized cases, with fresh-environment checks, useful failure +messages and independently verifiable evidence. External adoption is recorded when observed and +can guide later improvements. The current source alpha does not establish automatic generation, +saved developer time, lower maintenance cost or production support; those claims need specific evidence. ReproLock code is licensed under [Apache-2.0](LICENSE). Instrument Sans is distributed under the [SIL Open Font License 1.1](docs/assets/InstrumentSans-OFL.txt); see diff --git a/harness/build-log.md b/harness/build-log.md index 639fe98..0251964 100644 --- a/harness/build-log.md +++ b/harness/build-log.md @@ -1,5 +1,9 @@ # ReproLock Build Log + +> Coverage: the dated integration entries below document their original phases and are not a live project-status summary. Current scope is in [README](../README.md); completed phase details are indexed in [context](context/README.md). + + This is the central integration record for evidence-gated phases. Wave 0 creates this file; after that initialization, only the integration branch may update it. Task branches write their actual commands and evidence to `harness/context/.md`. diff --git a/harness/context/README.md b/harness/context/README.md index ef552b4..52a4004 100644 --- a/harness/context/README.md +++ b/harness/context/README.md @@ -1,5 +1,9 @@ # Phase Context Records + +> Existing numbered contexts are historical acceptance records, not pending assignments. Current work follows [README](../../README.md), [PROJECT_CHARTER](../../PROJECT_CHARTER.md) and a concrete new phase plan when needed. Preserve original checks and resource/authorization dates. + + Each task branch owns exactly one durable context file: ```text diff --git a/plans/00-repository-foundation.md b/plans/00-repository-foundation.md index aadce73..030c73a 100644 --- a/plans/00-repository-foundation.md +++ b/plans/00-repository-foundation.md @@ -1,5 +1,9 @@ # Wave 0 Repository Foundation ExecPlan + +> Historical phase plan. Preserve its original decisions and acceptance record; pending checkboxes, adoption gates and publishing permissions do not authorize or block a new phase. Current scope is in [README](../README.md), [PROJECT_CHARTER](../PROJECT_CHARTER.md) and the [plan index](README.md). + + > **Historical pre-v2 record.** This file preserves the commands and decisions observed during > Wave 0. Its public-target, parallel-Wave, package-topology, and successor assumptions were > superseded by the scoped clean-start baseline and do not authorize current work. diff --git a/plans/01-single-session-foundation-and-architecture.md b/plans/01-single-session-foundation-and-architecture.md index 4f9d3ab..55dbff5 100644 --- a/plans/01-single-session-foundation-and-architecture.md +++ b/plans/01-single-session-foundation-and-architecture.md @@ -1,5 +1,9 @@ # Single-session foundation and architecture ExecPlan + +> Historical phase plan. Preserve its original decisions and acceptance record; pending checkboxes, adoption gates and publishing permissions do not authorize or block a new phase. Current scope is in [README](../README.md), [PROJECT_CHARTER](../PROJECT_CHARTER.md) and the [plan index](README.md). + + ## Goal Produce one reviewable commit that gives ReproLock a minimal, executable local-functional-QA diff --git a/plans/02-local-functional-regression-spike-a.md b/plans/02-local-functional-regression-spike-a.md index ded5895..cc506ec 100644 --- a/plans/02-local-functional-regression-spike-a.md +++ b/plans/02-local-functional-regression-spike-a.md @@ -1,5 +1,9 @@ # Safe Unfollow #163 local functional-regression Spike A + +> Historical phase plan. Preserve its original decisions and acceptance record; pending checkboxes, adoption gates and publishing permissions do not authorize or block a new phase. Current scope is in [README](../README.md), [PROJECT_CHARTER](../PROJECT_CHARTER.md) and the [plan index](README.md). + + ## Goal Produce one independently checked, standalone Playwright regression test that fails for the diff --git a/plans/03-brand-verifiable-demo.md b/plans/03-brand-verifiable-demo.md index 634bea5..afa6c6c 100644 --- a/plans/03-brand-verifiable-demo.md +++ b/plans/03-brand-verifiable-demo.md @@ -1,5 +1,9 @@ # Brand and verifiable local Demo + +> Historical phase plan. Preserve its original decisions and acceptance record; pending checkboxes, adoption gates and publishing permissions do not authorize or block a new phase. Current scope is in [README](../README.md), [PROJECT_CHARTER](../PROJECT_CHARTER.md) and the [plan index](README.md). + + ## Goal and authorization Deliver a branded, runnable Safe Unfollow #163 Demo whose current result comes from actual diff --git a/plans/04-local-differential-verifier.md b/plans/04-local-differential-verifier.md index 32c3742..6b12d7f 100644 --- a/plans/04-local-differential-verifier.md +++ b/plans/04-local-differential-verifier.md @@ -1,5 +1,9 @@ # Local differential verification — execution plan + +> Historical phase plan. Preserve its original decisions and acceptance record; pending checkboxes, adoption gates and publishing permissions do not authorize or block a new phase. Current scope is in [README](../README.md), [PROJECT_CHARTER](../PROJECT_CHARTER.md) and the [plan index](README.md). + + Owner authorization: 2026-09-05 conversation, following the public-readiness audit and the proposal to accept a supplied local repository, two revisions and a candidate Playwright test. Product decision remains `SPIKE_CONDITIONAL`; this is a bounded value-validation increment. diff --git a/plans/05-demo-saved-run-readiness.md b/plans/05-demo-saved-run-readiness.md index ea33279..cb3572e 100644 --- a/plans/05-demo-saved-run-readiness.md +++ b/plans/05-demo-saved-run-readiness.md @@ -1,5 +1,9 @@ # Saved run readiness + +> Historical phase plan. Preserve its original decisions and acceptance record; pending checkboxes, adoption gates and publishing permissions do not authorize or block a new phase. Current scope is in [README](../README.md), [PROJECT_CHARTER](../PROJECT_CHARTER.md) and the [plan index](README.md). + + Observed problem: main `9e630b8` CI run `33902484660`, Node 24 browser test at `tests/playwright/demo.spec.ts:104`, displayed `Startup failed` after clicking its retained run. All 82 unit/process tests passed; Node 22 passed. The failure log is preserved in local ignored diff --git a/plans/06-drawdb-value-validation.md b/plans/06-drawdb-value-validation.md index 4c97ab9..1c966f4 100644 --- a/plans/06-drawdb-value-validation.md +++ b/plans/06-drawdb-value-validation.md @@ -1,5 +1,9 @@ # DrawDB candidate-verification experiment + +> Historical phase plan. Preserve its original decisions and acceptance record; pending checkboxes, adoption gates and publishing permissions do not authorize or block a new phase. Current scope is in [README](../README.md), [PROJECT_CHARTER](../PROJECT_CHARTER.md) and the [plan index](README.md). + + ## Goal and authorization Test whether the local candidate-verification workflow executes a second supplied/selected case diff --git a/plans/07-public-alpha-readiness.md b/plans/07-public-alpha-readiness.md index da4f0f4..0a53850 100644 --- a/plans/07-public-alpha-readiness.md +++ b/plans/07-public-alpha-readiness.md @@ -1,5 +1,9 @@ # Public alpha readiness + +> Historical phase plan. Preserve its original decisions and acceptance record; pending checkboxes, adoption gates and publishing permissions do not authorize or block a new phase. Current scope is in [README](../README.md), [PROJECT_CHARTER](../PROJECT_CHARTER.md) and the [plan index](README.md). + + ## Goal and authorization Prepare ReproLock for an honest public-source alpha. A new maintainer must be able to understand diff --git a/plans/README.md b/plans/README.md index 510bb3a..59e9f75 100644 --- a/plans/README.md +++ b/plans/README.md @@ -2,6 +2,11 @@ Multi-step work maintains one living plan under `plans/`, governed by root `PLANS.md`. +Plans `00` through `07` are completed or superseded phase records. Their old branches, release +permissions and external-adoption gates do not dispatch current work. The next engineering scope +is the complete existing-case workflow described in the current README and PROJECT_CHARTER. +Open a new phase plan only for the concrete task being executed; preserve historical evidence. + Use a stable lowercase identifier: ```text diff --git a/reference/ARCHITECTURE_AND_ACCEPTANCE_BASELINE.md b/reference/ARCHITECTURE_AND_ACCEPTANCE_BASELINE.md index e9ed286..3810bde 100644 --- a/reference/ARCHITECTURE_AND_ACCEPTANCE_BASELINE.md +++ b/reference/ARCHITECTURE_AND_ACCEPTANCE_BASELINE.md @@ -1,5 +1,9 @@ # ReproLock Architecture and Acceptance Baseline + +> Historical architecture/acceptance baseline. Current executable commands and exit codes are in [local verification](../docs/local-verification.md); current engineering scope is in [README](../README.md) and [PROJECT_CHARTER](../PROJECT_CHARTER.md). Old phase gates and release instructions do not dispatch new work. + + - **Status:** Phase baseline for human review - **Decision:** `CONDITIONAL GO` for architecture/foundation; product `GO` remains gated - **Scope:** Local functional QA on explicit user-supplied repositories and disposable targets