Skip to content

Implement REQ-MIGRATION-003: canonical TypeScript Config/Domain/Simulation/Diagnostics scaffolding #27

Closed
#29
Closed
Implement REQ-MIGRATION-003: canonical TypeScript Config/Domain/Simulation/Diagnostics scaffolding#27
#29
Labels
area:simulation-coreTick loop, ordering, determinism, configurationpriority:highImportant and time-sensitive; schedule ahead of normal worktype:architectureArchitecture, boundaries, contracts, or consequential design decisions

Description

@drevendev
drevendev
opened on Sep 3, 2026

Goal

Add the canonical TypeScript scaffolding required by REQ-MIGRATION-003 —
distinct Config, Domain, Simulation and Diagnostics module areas under src/ —
with no canonical economics/behavior and no changes to the legacy C# project.

Evidence

  • docs/spec/mirror/REQUIREMENTS_REGISTRY.csv row: REQ-MIGRATION-003, area
    MIGRATION, FILE=06 - Handoff/11 — REPOSITORY_MIGRATION_AND_MILESTONE_GATES.md,
    ANCHOR=Milestone 0 — Baseline lock and migration scaffolding, STATUS=READY,
    PRIORITY=P0, DEPENDS_ON=REQ-MIGRATION-001 (already IMPLEMENTED).
    Statement: "Add canonical TypeScript/Vite-capable Config, Domain, Simulation and
    Diagnostics scaffolding without moving legacy C# classes or adding canonical
    economics yet." Acceptance: "Legacy .NET build/tests remain green; canonical
    TypeScript scaffolding builds/tests independently; no canonical subsystem
    behavior is introduced in M0."
  • The same mirrored document's Milestone 0 section: "Add folders/namespaces for
    Config, Domain, Simulation and Diagnostics without moving legacy classes yet"
    and "Add a migration marker documenting which classes are legacy."
  • docs/adr/0002-typescript-canonical-engine.md (Accepted, 2026-09-03): "Canonical
    simulation behavior is implemented in TypeScript, under src/. From M1 onward
    every canonical subsystem lands there. M0 puts the scaffolding in place
    (REQ-MIGRATION-003).    " This is the researcher-recorded resolution
    (SPEC_CHANGELOG.md row RUNTIME-001) of the mirrored document's own
    conflicting C#-vs-browser wording elsewhere in the same file (its "Runtime
    implementation resolution" section says M0 "remains entirely inside the
    existing .NET 9 baseline"). Treating the ADR as authoritative over the stale
    wording is itself an assumption carried from the ADR's framing, not a fact this
    Issue re-derives — a claiming run should not need to re-litigate it, but should
    say so if it finds the ADR insufficient.
  • Issue Give canonical TypeScript work a required check #14 (closed; merged as PRs Add the canonical TypeScript toolchain #15/Make canonical TypeScript work verifiable #16) built the npm/TypeScript/Vite/Vitest
    toolchain and its required CI check, but explicitly listed "the canonical
    scaffolding itself" as a non-goal: "REQ-MIGRATION-003 is work for an author
    run, not for setup. Nothing economic belongs in src/ yet."
  • src/index.ts already carries the breadcrumb for this Issue: toolchainStatus()
    returns canonicalScaffolding: false with the comment "Flips to true in
    REQ-MIGRATION-003, which is where the scaffolding belongs," and
    src/index.test.ts asserts that false today.
  • Current repository state: src/ contains only index.ts and index.test.ts;
    no config/, domain/, simulation/ or diagnostics/ module areas exist yet.

Scope

  • Under src/, add four module areas matching the scaffolding named by
    REQ-MIGRATION-003: config/, domain/, simulation/, diagnostics/. Each
    gets a minimal placeholder module (e.g. an index.ts stating its responsibility
    boundary in a short comment) sufficient to prove the structure exists, compiles
    and is exercised by a test — no entity/ID/money types, no tick logic, no
    configuration schema, no economics.
  • Add a migration marker (location is an implementer decision — record it as a
    Decision comment on this Issue) documenting which TradeCraftSimulation
    classes are still legacy, per the Milestone 0 bullet and the mirrored
    document's "Legacy-to-canonical responsibility map" section.
  • Flip toolchainStatus().canonicalScaffolding in src/index.ts to true and
    update src/index.test.ts to match.
  • Add at least one test per new module area proving it builds/typechecks under
    Vitest.

Non-goals

  • No canonical economic behavior of any subsystem: no tick orchestrator, no
    registries, no keyed RNG, no config validation logic. Gate M0 requires that "no
    canonical subsystem behavior has been introduced yet."
  • No changes to TradeCraftSimulation/** or TradeCraftSimulation.Tests/** —
    legacy classes are not moved, renamed or deleted.
  • No M1 work (REQ-CORE-001, REQ-CONFIG-001..005, keyed RNG, world genesis) —
    those are separate, later requirements gated behind this one.
  • Does not reopen or re-resolve the mirrored document's internal wording tension
    beyond citing the researcher's existing ADR 0002 / RUNTIME-001 resolution.

Acceptance criteria

  • src/ contains distinct config/, domain/, simulation/, diagnostics/
    module areas, each with a minimal placeholder and no economic behavior.
  • A migration marker documents which legacy C# classes remain legacy.
  • toolchainStatus().canonicalScaffolding is true and its test reflects
    that.
  • npm ci, npm run typecheck, npm test and npm run build all succeed.
  • dotnet build --configuration Release and
    dotnet test --configuration Release remain green and unchanged in
    behavior (legacy build/tests untouched).
  • No TradeCraftSimulation/** or TradeCraftSimulation.Tests/** files are
    modified.
  • docs/spec/IMPLEMENTATION_STATUS.md gains/updates the REQ-MIGRATION-003
    row in the same pull request, naming the merge commit and the proving
    test(s), per AUTHOR_RUNBOOK.md section on feedback to the researcher.

Verification

npm ci
npm run typecheck
npm test
npm run build
dotnet restore
dotnet build --configuration Release --no-restore
dotnet test --configuration Release --no-build

Dependencies, authority, and risks

REQ-MIGRATION-001 (dependency) is already IMPLEMENTED. No additional
authority needed beyond the standing AUTHOR grants in AGENTS.md. Main risk:
picking scaffolding contents specific enough to look like early canonical
economics — keep every placeholder deliberately empty of behavior.

Activity

  1. drevendev
    added
    priority:highImportant and time-sensitive; schedule ahead of normal work
    type:architectureArchitecture, boundaries, contracts, or consequential design decisions
    area:simulation-coreTick loop, ordering, determinism, configuration
    status:readySpecified and unblocked; safe for an agent to claim
    on Sep 3, 2026

  2. drevendev commented on Sep 3, 2026

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

    QA correction before implementation: the final acceptance bullet currently asks the same pull request to record its own merge commit in docs/spec/IMPLEMENTATION_STATUS.md. That commit does not exist until after merge, and the repository already established the bounded reconciliation flow in AUTHOR_RUNBOOK.md / PR #21.

    For this Issue, treat the acceptance as:

    No product or economic requirement changes. This is a process/evidence correction so the task is achievable without inventing a nonexistent future commit.

  3. drevendev commented on Sep 3, 2026

    @drevendev
    drevendev
    on Sep 3, 2026
    OwnerAuthor

    AUTHOR claim

    • Role: AUTHOR
    • Scope: implement REQ-MIGRATION-003 per this Issue — add src/config/, src/domain/, src/simulation/, src/diagnostics/ placeholder module areas, a legacy migration marker, flip toolchainStatus().canonicalScaffolding to true, and update docs/spec/IMPLEMENTATION_STATUS.md with the REQ-MIGRATION-003 row as IN_PROGRESS (per the QA correction comment above — Merged in = pending until reconciliation).
    • Branch: claude/issue-27-canonical-scaffolding
    • Known blockers: none at claim time.
  4. drevendev
    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 3, 2026

  5. drevendev commented on Sep 3, 2026

    @drevendev
    drevendev
    on Sep 3, 2026
    OwnerAuthor

    Decision: the Milestone 0 migration marker lives at `docs/migration/LEGACY_MARKER.md` rather than inside `TradeCraftSimulation/`, because the Issue's acceptance criteria and non-goals require that no `TradeCraftSimulation/` file be modified in this change. The marker lists all nine current legacy classes and file paths, states the one-authoritative-owner-per-stock rule from the mirrored document's non-negotiable migration rules, and points to ADR 0002 for where canonical replacements land.

  6. drevendev
    added
    status:needs-reviewImplementation complete, awaiting acceptance
    and removed
    status:in-progressClaimed work with an active branch or pull request
    on Sep 3, 2026

  7. drevendev commented on Sep 3, 2026

    @drevendev
    drevendev
    on Sep 3, 2026
    OwnerAuthor

    AUTHOR handoff

    • Branch: claude/issue-27-canonical-scaffolding
    • Tested revision: 7944bc0c71032ef61af597dcf4298e0bd0c379e6
    • Pull request: Implement REQ-MIGRATION-003: canonical TypeScript scaffolding #29 (Closes #27)
    • Checks: npm ci passed, npm run typecheck passed, npm test passed (5 files/6 tests), npm run build passed, dotnet restore passed, dotnet build --configuration Release passed (0/0 warnings/errors), dotnet test --configuration Release passed (44/44, unchanged) — full evidence in the PR body.
    • Decisions: migration marker placed at docs/migration/LEGACY_MARKER.md (commented above); REQ-MIGRATION-003 row added to docs/spec/IMPLEMENTATION_STATUS.md as IN_PROGRESS with Merged in = pending, per the QA-correction comment above — reconciliation to IMPLEMENTED is follow-up work for a later run, not this PR.
    • Remaining: none for this unit of work.

    Status set to status:needs-review.

  8. drevendev commented on Sep 4, 2026

    @drevendev
    drevendev
    on Sep 4, 2026
    OwnerAuthor

    AUTHOR run — recording why no new Issue was opened (2026-09-04)

    This run's selection pass found no eligible item under AUTHOR_RUNBOOK.md section 2, items 1–5 (see comments on #30 and #31 for the Issue-level detail). That leaves item 6: read the specification navigation files and create one new ready Issue for the next unimplemented requirement.

    Checked REQUIREMENTS_REGISTRY.csv + SPEC_CHANGELOG.md + EXECUTION_ORDER.md against current M0 state:

    Net result: no registry requirement is currently eligible for a new ready Issue. This run made no code, label, or branch changes, and stops here per AGENTS.md's Blockers section — merging PR #29 (ACCEPTOR action, out of scope for AUTHOR) is what reopens the queue for the next AUTHOR run.

  9. drevendev
    closed this as completedin #29on Sep 4, 2026
  10. drevendev
    added a commit that references this issue on Sep 4, 2026

    Add canonical TypeScript scaffolding for REQ-MIGRATION-003 (#29)

    1fb0893
  11. drevendev
    removed
    status:needs-reviewImplementation complete, awaiting acceptance
    on Sep 4, 2026

  12. drevendev commented on Sep 4, 2026

    @drevendev
    drevendev
    on Sep 4, 2026
    OwnerAuthor

    ACCEPTOR verdict: ACCEPT and merged.

    Reviewed PR #29 at head revision 7944bc0c71032ef61af597dcf4298e0bd0c379e6, merged as 1fb089368434abc2d875a553225f6f73d042da41 (squash merge, branch deleted).

    Verification performed independently (not taken from the PR body):

    1. Required checks green at head — build-and-test, typescript, policy-guard all pass on gh pr checks 29.
    2. Acceptance criteria, each with evidence I observed:
      • src/config/, src/domain/, src/simulation/, src/diagnostics/ each exist with a minimal placeholder (no economic behavior) and a passing Vitest test — confirmed by reading the diff and running the suite.
      • docs/migration/LEGACY_MARKER.md lists all nine legacy classes; cross-checked against ls TradeCraftSimulation/*.cs — exact match (City, CsvLogger, Deal, Market, Pop, Program, Simulation, SimulationConfig, Storage).
      • toolchainStatus().canonicalScaffolding is true, test updated to match.
      • Ran myself at the PR head: npm ci, npm run typecheck (clean), npm test (5 files / 6 tests passed), npm run build (vite build succeeded).
      • Ran myself at the PR head: dotnet restore, dotnet build --configuration Release (0 warnings/errors), dotnet test --configuration Release (44/44 passed) — legacy build/tests unchanged and green, satisfying REQ-MIGRATION-003's dependency on REQ-MIGRATION-003 not touching legacy.
      • No TradeCraftSimulation/** file touched — confirmed via gh pr diff.
      • docs/spec/IMPLEMENTATION_STATUS.md gains the REQ-MIGRATION-003 row as IN_PROGRESS / Merged in = pending, per the prior QA-correction comment on PR Implement REQ-MIGRATION-003: canonical TypeScript scaffolding #29 (a PR cannot name its own future merge commit). This is a reasonable, explicitly-justified reading of that acceptance line, not a gap.
    3. Diff confined to declared scope — only src/config/**, src/domain/**, src/simulation/**, src/diagnostics/**, src/index.ts/src/index.test.ts, docs/migration/LEGACY_MARKER.md, docs/spec/IMPLEMENTATION_STATUS.md. No .github/workflows/**, AGENTS.md, or docs/zendev/** touched.
    4. No invariant or test weakened — the only test behavior change is src/index.test.ts flipping its assertion from false to true, which is exactly what acceptance criterion 3 requires; no invariant tests (money/stock conservation) exist in this scaffolding-only change.
    5. No secret, credential, or personal data — scanned the diff, none present.
    6. Handoff record — PR body contained outcome, tested revision, changed artifacts, acceptance criteria with status, checks table, assumptions/unknowns, highest-risk area, and remaining gate.

    Issue closed by the merge. Removed status:needs-review since the Issue is now closed.

    Follow-up noted in the PR itself: a later reconciliation run should flip the REQ-MIGRATION-003 row in docs/spec/IMPLEMENTATION_STATUS.md from IN_PROGRESS to IMPLEMENTED with this merge commit — that is separate work, not required for this Issue's closure.

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:simulation-coreTick loop, ordering, determinism, configurationpriority:highImportant and time-sensitive; schedule ahead of normal worktype:architectureArchitecture, boundaries, contracts, or consequential design decisions

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions