feat(docs): architecture case study and TASK-017 completion - #20
Merged
Merged
Conversation
- Add docs/case-study.md: comprehensive architecture case study covering core problem, domain model, dependency graph, scheduling/CPM, decision engine, explainability, scenario simulation, architecture/layering, persistence, testing strategy, measured performance (full benchmark table from benchmark/results.txt), CI/CD, and design tradeoffs - Add ADR-013: project naming (Trajectory) and availability (source code on GitHub, no deployment target for MVP) - Update PROJECT_PLAN.md resume story with concrete claims based on actual benchmark results and test counts - Update docs/architecture.md to reference the case study - Update README.md repository guide to include the case study - Update docs/handoff.md and docs/tasks.md to mark TASK-017 DONE - Append TASK-017 entry to docs/progress.md
- Remove stale 'final product name and availability' from human-decisions sections (case-study §14 and handoff), which contradicted ADR-013's resolved naming/availability decision; note the ADR-013 resolution instead - Clarify that benchmark datasets and algorithm outputs are deterministic while wall-clock timings naturally vary and are machine-dependent - Add machine context (OS, Node/npm versions, iteration counts) to the benchmark methodology
- Resolve the O(V+E) conflict: CPM passes are linear O(V+E), but topologicalOrder() uses an array ready queue that is re-sorted as nodes are added, so total ordering cost grows superlinearly. Clarify that calculateSchedule is dominated by the topological sort it invokes, and document the measured scaling (7.26ms at 1k tasks -> 799.31ms at 10k). - Correct the branch-protection claim: the four CI jobs run on every push/PR and surface as status checks, but requiring those checks before merge is a repository-settings action that remains to be configured by the owner. This aligns the case study with docs/handoff.md, which lists branch protection as pending. - Clarify that benchmark/results.txt is a git-ignored generated artifact (reproduced locally and uploaded as a CI artifact), not a committed file.
…list - Reword the 10k-task scenario-simulation observation as a benchmark-context measurement that is 'likely acceptable for occasional interactive use' and a candidate for optimization, rather than a flat acceptability judgment. - Add a short note in the CI/CD section that documentation consistency is treated as a review concern across the multiple state-describing files (implemented claims map to code, accepted decisions leave pending lists, future/human actions stay marked, benchmark figures trace to npm run benchmark output).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
TASK-017 — Architecture case study and final documentation
What this PR adds
docs/case-study.md— comprehensive architecture case study covering:docs/decisions.md— ADR-013 resolving project naming and availability:PROJECT_PLAN.md— resume story updated with concrete claims based on actual benchmark results and test counts (287 tests, 2 E2E specs, graph construction ~11ms at 10k tasks, recommendation ~22ms)Other updates
docs/architecture.md— references the case studyREADME.md— case study added to repository guidedocs/handoff.md— TASK-017 marked DONE, all phases completedocs/tasks.md— TASK-017 marked DONEdocs/progress.md— TASK-017 entry appendedVerification
npm run verifypasses (typecheck, 287 tests, lint, format)npm run buildsucceedsbenchmark/results.txt