Skip to content

REQ-VISUALIZATION-007: refresh README and public project documentation for M3 #355

Closed
Closed
REQ-VISUALIZATION-007: refresh README and public project documentation for M3#355
Labels
area:visualizationThe docs/ run viewerpriority:highImportant and time-sensitive; schedule ahead of normal worktype:featureNew simulation capability or observable behavior

Description

@drevendev
drevendev
opened on Sep 9, 2026

Goal

Make the repository's public text match the project that actually exists now. M3 must not ship with a polished simulation hidden behind stale README/migration wording.

Evidence

The current root README primarily documents the legacy C# implementation and mentions TypeScript as an ongoing migration, which does not reflect the current state where:

  • M1 and M2 milestones are complete with canonical TypeScript implementation in production on GitHub Pages
  • The canonical runtime is fully TypeScript with no C# in the critical path
  • M3 local-market implementation is feature-complete and tested
  • A new reader cannot easily understand the current architecture or access the deployed simulation

Prior milestone documentation reviews (REQ-VISUALIZATION-006) confirmed that public documentation is a completion gate for M3. The README must accurately represent completed work to satisfy milestone acceptance.

Requirement

  • REQ_ID: REQ-VISUALIZATION-007
  • Milestone: M3
  • Priority: P0 / priority:high
  • Specification: docs/spec/mirror/06 - Handoff/11 — REPOSITORY_MIGRATION_AND_MILESTONE_GATES.md
  • Owner override 2026-09-10: M3 representation/documentation is a hard completion gate. REQ-VISUALIZATION-006/007/008 are mandatory and together form 3/9 = 33.3% of M3 requirement-sized work.

Scope

Refresh the root README and directly linked public project documentation so a new reader can understand the current implementation without reading Drive or the migration history.

The public documentation should clearly explain:

  • what the project is and what the economic simulation is trying to model;
  • that M1+ canonical runtime is TypeScript/browser-capable;
  • that the retained C# toy is legacy/reference-oracle behavior, not the current target architecture;
  • current completed milestone state (M1/M2) and what M3 adds;
  • current M3 LocalMarket capabilities: price formation, deterministic clearing, atomic settlement, tax-aware money/goods flows, telemetry and deterministic replay/accounting constraints;
  • how to view GitHub Pages and what the viewer currently demonstrates;
  • accurate build, typecheck, test and run commands for the current repository;
  • where canonical public specs/status evidence live;
  • known intentional scope boundaries, without turning README into a giant technical spec.

Prefer concise, idiomatic English and useful navigation. Remove or rewrite stale statements that imply the old four-city C# toy is the current architecture.

Acceptance criteria

  1. Root README accurately describes the canonical TypeScript runtime and current M3 state.
  2. Legacy C# is clearly labeled as retained legacy/reference-oracle material.
  3. README links the deployed Pages experience prominently and explains what the user can observe there.
  4. Build/typecheck/test/run instructions match current repository commands and succeed from a clean checkout according to CI/current package scripts.
  5. M1/M2/M3 progress wording matches authoritative implementation evidence; no claim marks PARTIAL requirements complete.
  6. Directly linked public docs contain no obvious stale architecture/migration wording that contradicts the README.
  7. Text is concise, clear English with canonical terminology; important terms have short human-readable explanations.
  8. No new economic mechanism, formula, accounting identity or milestone semantics are invented.
  9. No docs/spec/mirror/ content is patched directly; specification mirror remains workflow-owned.
  10. Existing build/test gates remain green.

Verification

Verification checklist to confirm REQ-VISUALIZATION-007 is complete:

  1. Clone repository fresh and run npm ci && npm run typecheck && npm test — all pass (AC 4, 10)
  2. Read root README end-to-end: contains clear statement of current architecture, M1/M2 completion, M3 LocalMarket capabilities (AC 1, 7)
  3. Verify legacy C# is labeled as "legacy/reference-oracle" or similar, not described as current architecture (AC 2)
  4. Find link to GitHub Pages deployment; verify it works and README explains what viewer shows (AC 3)
  5. Spot-check referenced documentation files for stale C#/migration wording — none should contradict README (AC 6)
  6. Verify no acceptance criteria requirements are claimed as PARTIAL (AC 5)
  7. Search README for invented terminology: no new economic formulas, accounting identities, or milestone semantics (AC 8)
  8. Confirm no edits to docs/spec/mirror/ (AC 9)

Dependencies

None beyond current M3 being active. This work can and should proceed while REQ-MARKET-005 / REQ-ACCEPTANCE-004 correctness repairs continue.

Non-goals

  • Do not copy the entire handoff into README.
  • Do not rewrite canonical specification authority in repository prose.
  • Do not add marketing claims that are not demonstrated by the implementation.

Activity

  1. drevendev
    added
    priority:highImportant and time-sensitive; schedule ahead of normal work
    type:featureNew simulation capability or observable behavior
    area:visualizationThe docs/ run viewer
    status:readySpecified and unblocked; safe for an agent to claim
    on Sep 9, 2026

  2. drevendev commented on Sep 9, 2026

    @drevendev
    drevendev
    on Sep 9, 2026 – with ChatGPT Codex Connector
    OwnerAuthor

    RESEARCHER QA — bounded REQ-VISUALIZATION-007 public-doc audit on current master.

    The current README is not merely stale around the edges; it still presents the legacy four-city C# toy as the project itself. Concrete contradictions with the canonical/current repository state:

    1. Opening description says the product is “A toy economy across four trading cities” and describes fixed merchant/city behavior as current architecture. M1+ canonical runtime is TypeScript/browser-capable and the four-city C# model is now legacy/reference-oracle material.
    2. “The model”, “A turn”, “How a price moves”, and “How a deal works” all explain legacy mechanics as authoritative product behavior, including the 6-step turn, trader-pop transport model, MaxPriceStep, fixed money stock and cargo-loss transport. These must be either moved under a clearly labelled Legacy/reference section or removed from the default project explanation; they must not be blended with canonical M3 economics.
    3. Running instructions expose only dotnet run ... and reflection-style --config K=V overrides. Current package.json owns the canonical TS toolchain (npm ci, npm run typecheck, npm test, npm run build) and currently defines no canonical npm run simulation CLI. Do not invent a run command that does not exist; document the current supported canonical commands truthfully and keep the .NET command explicitly under Legacy/reference oracle.
    4. The README says Pages “reads the very CSV the simulator writes” and frames the page as the legacy 300-turn CSV viewer. Current Pages also contains deterministic M0/M1/M2 canonical milestone-preview artifacts, and M3 representation is now an explicit completion gate. README should describe what Pages actually demonstrates today and distinguish the legacy chart area from canonical milestone previews until M3 consolidation lands.
    5. Root package.json itself has stale public metadata: description = “Canonical TypeScript engine ... Scaffolding only until REQ-MIGRATION-003.” That milestone is long complete. Treat this as part of public-text freshness for REQ-VISUALIZATION-007: refresh README and public project documentation for M3 #355; replace it with a concise current description without claiming unfinished M3 rows are complete.
    6. Current Pages <title> / hero text still say “300 turns of a toy economy” / “Four cities, one toy economy”. That is consistent with legacy content but conflicts with a README that should present the canonical project first. REQ-VISUALIZATION-007: refresh README and public project documentation for M3 #355 does not need to redesign Pages (REQ-VISUALIZATION-006: M3 polished LocalMarket Pages experience #269 owns that), but any directly linked public wording touched by this PR should avoid reasserting the legacy toy as the whole project.

    Suggested minimal structure for the repair, without turning README into a spec:

    • 2–3 sentence project overview: autonomous deterministic economic simulation + canonical TypeScript runtime + GitHub Pages observatory/preview.
    • prominent Pages link and one paragraph on what is visible now.
    • “Current implementation status” with M1/M2 complete and M3 in progress; source truth = docs/spec/implementation_status.csv; do not mark REQ-MARKET-005 / REQ-ACCEPTANCE-004 complete while ledger says PARTIAL.
    • short “Canonical model” section covering only implemented/current M3 concepts at a human level.
    • “Development” with exact current npm commands and retained .NET verification commands.
    • “Legacy reference model” collapsed into a clearly labelled short section or link, preserving useful history without presenting it as canonical truth.
    • links to public spec/status docs and, once REQ-VISUALIZATION-008: publish M3 local-market explainer/reference articles #356 lands, the two explainer articles.

    Acceptance note: this QA does not request any economic/mechanical change. It is documentation authority cleanup only. Please keep docs/spec/mirror/ untouched.

  3. zendev-author commented on Sep 9, 2026

    @zendev-author
    zendev-authorbot
    on Sep 9, 2026
    Contributor

    AUTHOR claim

    Role: AUTHOR
    Scope: Implement REQ-VISUALIZATION-007 - refresh README and public project documentation for M3
    Branch: claude/issue-355-visualization-007
    Blockers: None identified

  4. zendev-author
    added
    status:in-progressClaimed work with an active branch or pull request
    and removed
    status:readySpecified and unblocked; safe for an agent to claim
    on Sep 9, 2026

  5. zendev-author commented on Sep 9, 2026

    @zendev-author
    zendev-authorbot
    on Sep 9, 2026
    Contributor

    AUTHOR handoff

    Branch: claude/issue-355-visualization-007
    Tested revision: 3602da1
    Pull request: #358

    Checks:

    • TypeScript: 536 tests passed, typecheck clean, build succeeded
    • C#/.NET: 45 tests passed, build clean (REQ-MIGRATION-003 maintained)

    Decisions:
    No design decisions required. This is a documentation refresh following the specified narrative requirements.

    Remaining gates:
    None identified within the work scope. The requirement cannot be recorded in the implementation ledger until the researcher indexes REQ-VISUALIZATION-007 in REQUIREMENTS_REGISTRY.csv, but this is expected flow — requirement IDs originate in the specification, not in the ledger.

    Status: Complete and ready for ACCEPTOR review.

  6. zendev-author
    added
    status:needs-reviewImplementation complete, awaiting acceptance
    and removed
    status:in-progressClaimed work with an active branch or pull request
    on Sep 9, 2026
  7. zendev-acceptor
    closed this as completedin 8bfd4feon Sep 9, 2026
  8. zendev-acceptor
    removed
    status:needs-reviewImplementation complete, awaiting acceptance
    on Sep 9, 2026
  9. drevendev
    added a commit that references this issue on Sep 10, 2026

    ledger: record the merged README refresh as a PARTIAL slice (#380)

    7a1b6d0
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:visualizationThe docs/ run viewerpriority:highImportant and time-sensitive; schedule ahead of normal worktype:featureNew simulation capability or observable behavior

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions