@difflab/difflab-cli 0.10.0 → 0.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +9 -3
- package/dist/index.js +276 -106
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -66,7 +66,9 @@ difflab-cli templates list
|
|
|
66
66
|
difflab-cli templates scaffold spec-driven-plan docs/plans first-plan.md --cwd /absolute/project/path
|
|
67
67
|
```
|
|
68
68
|
|
|
69
|
-
The CLI defaults `--cwd` to its current directory. The MCP server exposes `template_list({})` and `scaffold({"name":"spec-driven-plan","cwd":"/absolute/project/path","path":"docs/plans","filename":"first-plan.md"})`. Both interfaces take a hyphenated template name, a relative destination **directory** (`path`, or `.` for `cwd`), and a separate **filename**. MCP always requires an absolute existing `cwd`. Missing destination directories are created. Available names: `spec-driven-plan`, `software-architecture-design`, `architecture-decision-record`, `product-requirements-document`, `agents`, `code-review`, `planning-intent`, `ui-component-architecture`, `pull-request-description` (adapted from Diffpi's PR template), `flow-definition`, `flow-instance`, `exploration-summary`, `exploration-research`, `exploration-proposal`, and `poc-readme`.
|
|
69
|
+
The CLI defaults `--cwd` to its current directory. The MCP server exposes `template_list({})` and `scaffold({"name":"spec-driven-plan","cwd":"/absolute/project/path","path":"docs/plans","filename":"first-plan.md"})`. Both interfaces take a hyphenated template name, a relative destination **directory** (`path`, or `.` for `cwd`), and a separate **filename**. MCP always requires an absolute existing `cwd`. Missing destination directories are created. Available names: `spec-driven-plan`, `software-architecture-design`, `architecture-decision-record`, `product-requirements-document`, `agents`, `code-review`, `code-review-rubric`, `planning-intent`, `ui-component-architecture`, `pull-request-description` (adapted from Diffpi's PR template), `flow-definition`, `flow-instance`, `exploration-summary`, `exploration-research`, `exploration-proposal`, and `poc-readme`.
|
|
70
|
+
|
|
71
|
+
Reviews scaffold `code-review` as `REVIEW.md` and `code-review-rubric` as `rubric.yaml` in `.difflab/reviews/YYMMDD-name`. The installed rubric is `~/.difflab/templates/code-review-rubric.yaml`. Fill its criterion results during the review. File-scoped criteria require a path-tagged result for every changed source file. Function findings can include `file:line` locations. Evidence guidance and review instructions stay in the review skill, outside the lean YAML template.
|
|
70
72
|
|
|
71
73
|
Use `difflab-cli templates scaffold agents . AGENTS.md --cwd /absolute/project/path` to start repository guidance. Fill the prompts with known rules and remove unused prompts. The template separates Hard Rules, Organization, Style, and Testing. Hard Rules name required task runners and repository tools. Organization separates directory layout from section headers, code ordering, and grouping within files. Review addressing saves explicit user repository rules immediately and marks inferred or uncertain rules with `[Proposed]`. It asks before reorganizing existing guidance to match the template and adapts the existing structure if permission is declined. It retains terse file-level organization rules and keeps guidance within 500 soft-wrapped source lines.
|
|
72
74
|
|
|
@@ -74,9 +76,13 @@ On first use, missing bundled templates and filled examples are copied to `~/.di
|
|
|
74
76
|
|
|
75
77
|
The portable `skills/difflab-plan`, `skills/difflab-review`, `skills/difflab-flow`, `skills/difflab-explore`, `skills/difflab-adr`, and `skills/difflab-poc` directories contain natural-language agent workflows for these templates. Install each skill in your client's Agent Skills directory. The MCP-only `log_append({"path":"/absolute/physical/project-store/plans/YYMMDD-name/logs.txt","message":"Phase started"})` tool creates an append-only progress log on first use; pass the physical path, not the `.difflab` symlink. There is no log CLI command.
|
|
76
78
|
|
|
77
|
-
The [plan authoring guide](../../skills/difflab-plan/references/authoring.md) requires component/process/artifact visuals, compact interfaces, and a nested repo tree at the start of `Consequences`. Add a `Testing` outline
|
|
79
|
+
The [plan authoring guide](../../skills/difflab-plan/references/authoring.md) requires component/process/artifact visuals, compact interfaces, and a nested repo tree at the start of `Consequences`. Add a `Testing` outline with `[M/A/D/R]` notation and BDD-style `given`/`when`/`then` clauses mapped to existing suites or clearly labeled manual acceptance checks. Keep expected commit and green-CI gates, including for `plan go --commit`. That flag permits scoped commits. Push requires separate authorization. Write `N/A.` when infrastructure stays unchanged. Source examples live in the skill's `references/examples/` and are not CLI templates.
|
|
80
|
+
|
|
81
|
+
The [review rubric](../../skills/difflab-review/references/rubric.md) follows written `AGENTS.md` rules and named style guides. Existing patterns are context, not requirements. Flag material antipatterns even when nearby code shares them. Refactor unclear code at the scope needed. Prefer outside-in tests (`e2e` > `integration` > `unit`) with human-verifiable outputs, and scrutinize unit test organization for BDD/Gherkin structure and clear Arrange/Act/Assert blocks. Untested private functions alone are not findings. Keep whole reports and comments short (one sentence per comment ideally) and use simple English; prefer code snippets or diagrams over walls of text. State findings once and keep detailed coverage in YAML. Omit nitpicks and minor optimizations. Explicit security/performance focuses deepen those audits.
|
|
82
|
+
|
|
83
|
+
Reviews keep the selected frontier model regardless of vendor. One reviewer covers the full rubric. `--bg` runs a complete review in the background. `--council [model-a,model-b]` uses full reviewers per model and saves reports under `council/`. Names accept aliases and clear typos. The lead aggregates supported findings and publishes once. `--adversarial` challenges all dimensions, including Security. Missing model capabilities or incomplete passes are reported honestly.
|
|
78
84
|
|
|
79
|
-
|
|
85
|
+
PR creation through `pr new`, create, open, or draft uses the installed `pull-request-description` template. Fill its sections before creating the request, then read the saved body back. `pr merge --squash` selects a native forge squash merge before the operation. These are Agent Skill requests, not CLI subcommands.
|
|
80
86
|
|
|
81
87
|
For an upgrade, reinstall changed skills and reload the client. Back up and move aside only the installed templates/examples you want refreshed, then list templates again. For these changes, inspect `~/.difflab/templates/{spec-driven-plan,code-review}.md` and `examples/{plan-feature,plan-migration,review-change}.md`. Preserve customizations in backups and merge deliberately; never reset the whole directory. Older templates still work: skills add missing subsections to generated documents while preserving human content and existing phase completion state.
|
|
82
88
|
|
package/dist/index.js
CHANGED
|
@@ -48362,7 +48362,7 @@ var spec_driven_plan_default = `# [Outcome to deliver]
|
|
|
48362
48362
|
|
|
48363
48363
|
### Big Ideas
|
|
48364
48364
|
|
|
48365
|
-
[Show changed component relationships with a component diagram, new processes with flowcharts, and new file-based artifacts with trees or suitable visuals. Use Mermaid and fenced text where useful. Keep decisions, responsibilities, invariants, and important failure behavior beside the relevant visual. Draw only the affected parts; keep enough detail to execute without the original chat.]
|
|
48365
|
+
[Lead with compact diagrams. Minimize prose and do not repeat the visual. Use short sentences and familiar words. Show changed component relationships with a component diagram, new processes with flowcharts, and new file-based artifacts with trees or suitable visuals. Use Mermaid and fenced text where useful. Keep decisions, responsibilities, invariants, and important failure behavior beside the relevant visual. Draw only the affected parts; keep enough detail to execute without the original chat.]
|
|
48366
48366
|
|
|
48367
48367
|
### Infrastructure Changes
|
|
48368
48368
|
|
|
@@ -48376,11 +48376,11 @@ var spec_driven_plan_default = `# [Outcome to deliver]
|
|
|
48376
48376
|
|
|
48377
48377
|
#### Repo Changes
|
|
48378
48378
|
|
|
48379
|
-
[Start with a selected file tree:
|
|
48379
|
+
[Start with a selected file tree: [M] modified, [A] added, [D] deleted, [R] renamed before changed filenames, including tests. Identify the largest edits in a short note. Include new modules and meaningful structural changes. Use real inspected paths; label proposed files. State when nothing is removed.]
|
|
48380
48380
|
|
|
48381
48381
|
#### Testing
|
|
48382
48382
|
|
|
48383
|
-
[Show a nested outline of
|
|
48383
|
+
[Inspect the actual test setup first. Show a nested outline of behavior checks mapped to existing suites and configured tasks, using [M], [A], [D], or [R] notation on suites and scenarios just like Repo Changes. Prefer BDD-style test organization with nested given/when/then or it clauses. Label skill checks without a harness as manual acceptance. Do not invent an end-to-end suite or runner. Name the entry point, input/action, and expected result for each scenario. Reuse existing fixtures and suites. Match the scenarios to requirements and phase checks.]
|
|
48384
48384
|
|
|
48385
48385
|
#### Trade-offs
|
|
48386
48386
|
|
|
@@ -48662,7 +48662,10 @@ var code_review_default = `# Review: [change or pull request]
|
|
|
48662
48662
|
|
|
48663
48663
|
- **Revision:** [commit or diff]
|
|
48664
48664
|
- **Intent:** [stated objective and source]
|
|
48665
|
-
- **Reviewer:** [
|
|
48665
|
+
- **Reviewer:** [actual model identity]
|
|
48666
|
+
- **Mode:** [normal/adversarial; single model or council with linked model reports]
|
|
48667
|
+
|
|
48668
|
+
[Use short sentences, active voice, and familiar words throughout. Keep section assessments brief and link to findings instead of repeating them. Keep detailed criterion coverage in rubric.yaml. Apply AGENTS.md and named style guides. Informal conventions are context, not requirements. Flag material antipatterns even when existing code shares them.]
|
|
48666
48669
|
|
|
48667
48670
|
## Intent Delivery
|
|
48668
48671
|
|
|
@@ -48670,23 +48673,23 @@ var code_review_default = `# Review: [change or pull request]
|
|
|
48670
48673
|
|
|
48671
48674
|
## Readability
|
|
48672
48675
|
|
|
48673
|
-
[Do names and code structure show what happens? Compare names with behavior, side effects, and callers.
|
|
48676
|
+
[Do names and code structure show what happens? Compare names with behavior, side effects, and callers. Apply written naming rules. Do not enforce harmless informal patterns. Flag misleading names and flows that are hard to follow.]
|
|
48674
48677
|
|
|
48675
48678
|
## Semantic Organization
|
|
48676
48679
|
|
|
48677
|
-
[Do modules have clear roles and useful public APIs? Identify mixed responsibilities and unclear ownership. Refactor or simplify at the scope needed to make the change understandable, including across files. Keep unrelated work out of scope.]
|
|
48680
|
+
[Do modules have clear roles and useful public APIs? Are exported types meaningful for the module role? Are methods and classes easy to discover and use? Identify mixed responsibilities and unclear ownership. Refactor or simplify at the scope needed to make the change understandable, including across files. Keep unrelated work out of scope.]
|
|
48678
48681
|
|
|
48679
48682
|
## Maintainability
|
|
48680
48683
|
|
|
48681
|
-
[Does the change
|
|
48684
|
+
[Does the change remain understandable and maintainable under applicable written rules? Existing antipatterns do not justify new ones. Check new fields, types, helpers, and dependencies against existing code and callers. Reuse suitable code and remove needless complexity.]
|
|
48682
48685
|
|
|
48683
48686
|
## Reliability/Testing
|
|
48684
48687
|
|
|
48685
|
-
[Prioritize end-to-end application behavior, then module behavior through public APIs, then focused unit behavior with public APIs first. Name missing observable contracts or regressions; do not demand coverage of every function or a percentage. Check semantic grouping, clear Arrange/Act/Assert blocks, fixtures, and existing shared helpers. Flag walls of repeated setup or interleaved actions/assertions that hide the behavior. Report executed checks and limits honestly.]
|
|
48688
|
+
[Prioritize end-to-end application behavior, then module behavior through public APIs, then focused unit behavior with public APIs first. Flag tests that only verify external dependencies rather than the repository's source behavior or integration contract. Require test names to identify the function or functionality tested and its expected behavior, regardless of grouping style. Name missing observable contracts or regressions; do not demand coverage of every function or a percentage. Check semantic grouping, clear Arrange/Act/Assert blocks, fixtures, and existing shared helpers. Flag walls of repeated setup or interleaved actions/assertions that hide the behavior. Report executed checks and limits honestly.]
|
|
48686
48689
|
|
|
48687
|
-
##
|
|
48690
|
+
## Documentation
|
|
48688
48691
|
|
|
48689
|
-
[
|
|
48692
|
+
[Flag walls of text, complex language, and text that only restates the implementation. Require concise, simple-English explanations. Prefer diagrams when they clarify structures, flows, or relationships better than long prose.]
|
|
48690
48693
|
|
|
48691
48694
|
## Performance
|
|
48692
48695
|
|
|
@@ -48694,11 +48697,11 @@ var code_review_default = `# Review: [change or pull request]
|
|
|
48694
48697
|
|
|
48695
48698
|
## Security
|
|
48696
48699
|
|
|
48697
|
-
[
|
|
48700
|
+
[Optional in normal mode: select for a security focus or --adversarial. Adversarial mode challenges all applicable dimensions. Otherwise state that it was not selected. Report clear security defects discovered by other dimensions without claiming a security audit. Avoid unrelated hardening requests.]
|
|
48698
48701
|
|
|
48699
48702
|
## Change Requests
|
|
48700
48703
|
|
|
48701
|
-
Use short comments
|
|
48704
|
+
State each finding once here, with its issue, effect, and useful fix. Use short, plain-English sentences for the whole report, including generated comments and replies. Include a suggested change when a concrete fix is available. State the issue and its effect directly. Phrase recommendations with \u201CLet's\u201D, \u201CI suggest\u201D, or \u201CI recommend\u201D. Include a short snippet or suggested patch only when it clarifies the fix. Use the scope that fixes the problem, including a refactor when needed. Group repeated instances of one cause. Omit repeated context, nitpicks, minor optimizations, and speculative findings. End each generated request and response with its model attribution quote. Preserve human text unchanged.
|
|
48702
48705
|
|
|
48703
48706
|
### [file:line \u2014 request]
|
|
48704
48707
|
|
|
@@ -48715,7 +48718,7 @@ Use short comments in simple English. State the problem and its effect directly.
|
|
|
48715
48718
|
|
|
48716
48719
|
| Severity | Location | Evidence and impact | Required change or question |
|
|
48717
48720
|
| --- | --- | --- | --- |
|
|
48718
|
-
| [blocking/consider/note] | [file:line] | [
|
|
48721
|
+
| [blocking/consider/note] | [file:line] | [short link to Change Request; do not repeat its text] | [short action or link] |
|
|
48719
48722
|
|
|
48720
48723
|
## Overall Assessment
|
|
48721
48724
|
|
|
@@ -48724,10 +48727,186 @@ Use short comments in simple English. State the problem and its effect directly.
|
|
|
48724
48727
|
## Verification and Limits
|
|
48725
48728
|
|
|
48726
48729
|
- **Checks run:** [command and result.]
|
|
48727
|
-
- **Not verified:** [environment, path, or
|
|
48730
|
+
- **Not verified:** [environment, path, behavior, or applicable repository guidance that could not be checked.]
|
|
48731
|
+
- **Council:** [source reports, actual model identities, unresolved disagreements, or not selected.]
|
|
48732
|
+
- **Rubric:** [path to the copied YAML rubric with completed criterion results. Disclose missing, pending, skipped, or stale results.]
|
|
48728
48733
|
`;
|
|
48729
48734
|
var init_code_review = () => {};
|
|
48730
48735
|
|
|
48736
|
+
// templates/code-review-rubric.yaml
|
|
48737
|
+
var code_review_rubric_default = `version: 1
|
|
48738
|
+
review_defaults:
|
|
48739
|
+
model_policy: retain-frontier
|
|
48740
|
+
review:
|
|
48741
|
+
base_revision: null
|
|
48742
|
+
head_revision: null
|
|
48743
|
+
working_tree: null
|
|
48744
|
+
changed_files: []
|
|
48745
|
+
exclusions: []
|
|
48746
|
+
reviewers: []
|
|
48747
|
+
model_inputs: []
|
|
48748
|
+
model_results: []
|
|
48749
|
+
sections:
|
|
48750
|
+
- title: Intent Delivery
|
|
48751
|
+
criteria:
|
|
48752
|
+
- id: intent.objective
|
|
48753
|
+
scope: review
|
|
48754
|
+
default_severity: blocking
|
|
48755
|
+
issue: The change contradicts its stated intent or omits required behavior.
|
|
48756
|
+
results: []
|
|
48757
|
+
- id: intent.scope
|
|
48758
|
+
scope: review
|
|
48759
|
+
default_severity: consider
|
|
48760
|
+
issue: The change includes work outside its stated scope.
|
|
48761
|
+
results: []
|
|
48762
|
+
- title: Readability
|
|
48763
|
+
criteria:
|
|
48764
|
+
- id: readability.function-names
|
|
48765
|
+
scope: file
|
|
48766
|
+
default_severity: consider
|
|
48767
|
+
issue: >-
|
|
48768
|
+
Function or other names misrepresent behavior, hide side effects, or violate written naming rules.
|
|
48769
|
+
results: []
|
|
48770
|
+
- id: readability.structure
|
|
48771
|
+
scope: file
|
|
48772
|
+
default_severity: consider
|
|
48773
|
+
issue: The changed flow is materially hard to follow.
|
|
48774
|
+
results: []
|
|
48775
|
+
- title: Semantic Organization
|
|
48776
|
+
criteria:
|
|
48777
|
+
- id: organization.roles
|
|
48778
|
+
scope: file
|
|
48779
|
+
default_severity: consider
|
|
48780
|
+
issue: A module mixes responsibilities or its imports, exports, or public API obscure its role.
|
|
48781
|
+
results: []
|
|
48782
|
+
- id: organization.architecture
|
|
48783
|
+
scope: review
|
|
48784
|
+
default_severity: consider
|
|
48785
|
+
issue: Files or classes mix responsibilities, obscure ownership, or violate written architecture rules.
|
|
48786
|
+
results: []
|
|
48787
|
+
- id: organization.api-ergonomics
|
|
48788
|
+
scope: applicable-file
|
|
48789
|
+
applies_when: Added or modified public APIs, exported types, methods, or classes.
|
|
48790
|
+
default_severity: consider
|
|
48791
|
+
issue: Public APIs expose types unrelated to the module role or are hard to discover and use.
|
|
48792
|
+
results: []
|
|
48793
|
+
- id: organization.new-files
|
|
48794
|
+
scope: applicable-file
|
|
48795
|
+
applies_when: Added source files that introduce a module or submodule. A rename alone does not qualify.
|
|
48796
|
+
default_severity: consider
|
|
48797
|
+
issue: >-
|
|
48798
|
+
A new file lacks a justified module boundary or contains functions that belong in an existing module.
|
|
48799
|
+
results: []
|
|
48800
|
+
- id: organization.file-structure
|
|
48801
|
+
scope: file
|
|
48802
|
+
default_severity: consider
|
|
48803
|
+
issue: A file breaks the project-prescribed structure or declaration order.
|
|
48804
|
+
results: []
|
|
48805
|
+
- title: Maintainability
|
|
48806
|
+
criteria:
|
|
48807
|
+
- id: maintainability.concepts
|
|
48808
|
+
scope: review
|
|
48809
|
+
default_severity: consider
|
|
48810
|
+
issue: >-
|
|
48811
|
+
New fields, types, wrappers, helpers, dependencies, or layers lack a justified use and add needless complexity.
|
|
48812
|
+
results: []
|
|
48813
|
+
- id: maintainability.complexity
|
|
48814
|
+
scope: applicable-file
|
|
48815
|
+
applies_when: >-
|
|
48816
|
+
Files with added or changed executable functions. For new functions, assess whether the introduced decision paths are justified.
|
|
48817
|
+
default_severity: consider
|
|
48818
|
+
issue: Cyclomatic complexity grows without justification from the required behavior.
|
|
48819
|
+
results: []
|
|
48820
|
+
- id: maintainability.utilities
|
|
48821
|
+
scope: review
|
|
48822
|
+
default_severity: consider
|
|
48823
|
+
issue: Duplicated state or behavior, or inline work, makes a function harder to read or maintain.
|
|
48824
|
+
results: []
|
|
48825
|
+
- id: maintainability.packages
|
|
48826
|
+
scope: review
|
|
48827
|
+
default_severity: consider
|
|
48828
|
+
issue: >-
|
|
48829
|
+
Custom code recreates functionality that an established, widely used package suitably provides.
|
|
48830
|
+
results: []
|
|
48831
|
+
- title: Reliability/Testing
|
|
48832
|
+
criteria:
|
|
48833
|
+
- id: testing.correctness
|
|
48834
|
+
scope: file
|
|
48835
|
+
default_severity: blocking
|
|
48836
|
+
issue: The changed code produces incorrect behavior.
|
|
48837
|
+
results: []
|
|
48838
|
+
- id: testing.application
|
|
48839
|
+
scope: review
|
|
48840
|
+
default_severity: consider
|
|
48841
|
+
issue: >-
|
|
48842
|
+
Required behavior lacks outside-in test evidence (e2e > integration > unit), or e2e/integration tests lack human-verifiable outputs such as snapshots, test logs, or JSON outputs.
|
|
48843
|
+
results: []
|
|
48844
|
+
- id: testing.relevance
|
|
48845
|
+
scope: applicable-file
|
|
48846
|
+
applies_when: Added or modified test files.
|
|
48847
|
+
default_severity: consider
|
|
48848
|
+
issue: >-
|
|
48849
|
+
Verbose unit tests pad coverage without proving real contracts, or a test verifies external dependency behavior without establishing behavior of the repository's own source code.
|
|
48850
|
+
results: []
|
|
48851
|
+
- id: testing.names
|
|
48852
|
+
scope: applicable-file
|
|
48853
|
+
applies_when: Added or modified test files.
|
|
48854
|
+
default_severity: consider
|
|
48855
|
+
issue: >-
|
|
48856
|
+
A test name does not identify the function or functionality tested and its expected behavior.
|
|
48857
|
+
results: []
|
|
48858
|
+
- id: testing.arrange-act-assert
|
|
48859
|
+
scope: applicable-file
|
|
48860
|
+
applies_when: Added or modified test files.
|
|
48861
|
+
default_severity: consider
|
|
48862
|
+
issue: >-
|
|
48863
|
+
Test organization lacks clear BDD/Gherkin structure (given/when/then) or interleaves setup, actions, and assertions so coverage or expected results are hard to see.
|
|
48864
|
+
results: []
|
|
48865
|
+
- id: testing.fixtures
|
|
48866
|
+
scope: applicable-file
|
|
48867
|
+
applies_when: Added or modified tests, fixtures, test setup, or test utility files.
|
|
48868
|
+
default_severity: consider
|
|
48869
|
+
issue: >-
|
|
48870
|
+
Repeated setup, unsuitable fixtures, or recreated shared utilities obscure tests or duplicate existing helpers.
|
|
48871
|
+
results: []
|
|
48872
|
+
- title: Documentation
|
|
48873
|
+
criteria:
|
|
48874
|
+
- id: documentation.conciseness
|
|
48875
|
+
scope: applicable-file
|
|
48876
|
+
applies_when: Added or modified documentation, including documentation comments.
|
|
48877
|
+
default_severity: consider
|
|
48878
|
+
issue: Long, dense, or complex text makes documentation hard to understand.
|
|
48879
|
+
results: []
|
|
48880
|
+
- id: documentation.redundancy
|
|
48881
|
+
scope: applicable-file
|
|
48882
|
+
applies_when: Added or modified documentation, including documentation comments.
|
|
48883
|
+
default_severity: consider
|
|
48884
|
+
issue: Documentation repeats the implementation or other text without adding useful context.
|
|
48885
|
+
results: []
|
|
48886
|
+
- id: documentation.visuals
|
|
48887
|
+
scope: applicable-file
|
|
48888
|
+
applies_when: Added or modified documentation that explains structures, flows, or relationships.
|
|
48889
|
+
default_severity: consider
|
|
48890
|
+
issue: A long textual explanation obscures information that a diagram would make clearer.
|
|
48891
|
+
results: []
|
|
48892
|
+
- title: Performance
|
|
48893
|
+
criteria:
|
|
48894
|
+
- id: performance.regressions
|
|
48895
|
+
scope: review
|
|
48896
|
+
default_severity: consider
|
|
48897
|
+
issue: The change causes a material performance regression.
|
|
48898
|
+
results: []
|
|
48899
|
+
- title: Security
|
|
48900
|
+
optional: true
|
|
48901
|
+
criteria:
|
|
48902
|
+
- id: security.defects
|
|
48903
|
+
scope: review
|
|
48904
|
+
default_severity: blocking
|
|
48905
|
+
issue: The change exposes secrets or breaks authorization or a trust boundary.
|
|
48906
|
+
results: []
|
|
48907
|
+
`;
|
|
48908
|
+
var init_code_review_rubric = () => {};
|
|
48909
|
+
|
|
48731
48910
|
// templates/planning-intent.md
|
|
48732
48911
|
var planning_intent_default = `# Intent: [short name]
|
|
48733
48912
|
|
|
@@ -49089,8 +49268,6 @@ Project owners need to invite teammates without sharing credentials. Recipients
|
|
|
49089
49268
|
|
|
49090
49269
|
### Big Ideas
|
|
49091
49270
|
|
|
49092
|
-
Keep invitation policy in the service and transport concerns in the handler. Store a single-use token hash, project, recipient, and expiry. Use the existing mail queue; no new service is needed.
|
|
49093
|
-
|
|
49094
49271
|
\`\`\`mermaid
|
|
49095
49272
|
flowchart LR
|
|
49096
49273
|
HTTP["HTTP handler"] --> Service["Invitation service<br/>eligibility and acceptance"]
|
|
@@ -49098,7 +49275,7 @@ flowchart LR
|
|
|
49098
49275
|
Service --> Queue["Existing mail queue"]
|
|
49099
49276
|
\`\`\`
|
|
49100
49277
|
|
|
49101
|
-
|
|
49278
|
+
Store only the token hash. Save before queueing delivery. An email outage must not lose the invitation.
|
|
49102
49279
|
|
|
49103
49280
|
\`\`\`mermaid
|
|
49104
49281
|
flowchart TD
|
|
@@ -49128,34 +49305,37 @@ Never log raw tokens. Apply the existing request rate limit to creation; do not
|
|
|
49128
49305
|
|
|
49129
49306
|
#### Repo Changes
|
|
49130
49307
|
|
|
49131
|
-
Illustrative paths:
|
|
49308
|
+
Illustrative paths: \`[M]\` modified, \`[A]\` added, \`[D]\` deleted, \`[R]\` renamed. No files are removed or renamed. \`service.ts\` contains the largest edits.
|
|
49132
49309
|
|
|
49133
49310
|
\`\`\`text
|
|
49134
49311
|
src/
|
|
49135
49312
|
\u251C\u2500\u2500 invitations/
|
|
49136
|
-
\u2502 \u251C\u2500\u2500 store.ts
|
|
49137
|
-
\u2502 \u251C\u2500\u2500 service.ts
|
|
49138
|
-
\u2502 \u2514\u2500\u2500 service.spec.ts
|
|
49313
|
+
\u2502 \u251C\u2500\u2500 [A] store.ts persistence and transaction
|
|
49314
|
+
\u2502 \u251C\u2500\u2500 [A] service.ts invitation policy
|
|
49315
|
+
\u2502 \u2514\u2500\u2500 [A] service.spec.ts public API with real test store
|
|
49139
49316
|
\u2514\u2500\u2500 http/
|
|
49140
|
-
\u251C\u2500\u2500 routes.ts
|
|
49141
|
-
\u251C\u2500\u2500 invitations.ts
|
|
49142
|
-
\u2514\u2500\u2500 invitations.spec.ts
|
|
49317
|
+
\u251C\u2500\u2500 [M] routes.ts register invitation handlers
|
|
49318
|
+
\u251C\u2500\u2500 [A] invitations.ts transport and authorization
|
|
49319
|
+
\u2514\u2500\u2500 [A] invitations.spec.ts application request scenarios
|
|
49143
49320
|
\`\`\`
|
|
49144
49321
|
|
|
49145
49322
|
#### Testing
|
|
49146
49323
|
|
|
49147
49324
|
\`\`\`text
|
|
49148
|
-
|
|
49149
|
-
\
|
|
49150
|
-
|
|
49151
|
-
|
|
49152
|
-
|
|
49153
|
-
\u2514\u2500\u2500
|
|
49154
|
-
|
|
49155
|
-
\u2514\u2500\u2500
|
|
49325
|
+
src/
|
|
49326
|
+
\u251C\u2500\u2500 http/
|
|
49327
|
+
\u2502 \u2514\u2500\u2500 [A] invitations.spec.ts (application behavior)
|
|
49328
|
+
\u2502 \u2514\u2500\u2500 [A] describe invitation endpoints
|
|
49329
|
+
\u2502 \u251C\u2500\u2500 [A] given an owner invite, when recipient accepts, then membership appears
|
|
49330
|
+
\u2502 \u2514\u2500\u2500 [A] given a wrong recipient or expired/used token, when accepted, then it rejects without changing state
|
|
49331
|
+
\u2514\u2500\u2500 invitations/
|
|
49332
|
+
\u2514\u2500\u2500 [A] service.spec.ts (public module behavior)
|
|
49333
|
+
\u2514\u2500\u2500 [A] describe invitation service
|
|
49334
|
+
\u251C\u2500\u2500 [A] given a failed transaction, when accepting, then membership and token changes roll back
|
|
49335
|
+
\u2514\u2500\u2500 [A] given an email failure, when creating, then the saved invitation stays pending for retry
|
|
49156
49336
|
\`\`\`
|
|
49157
49337
|
|
|
49158
|
-
Use
|
|
49338
|
+
Use BDD-style nested \`given\`/\`when\`/\`then\` scenarios in \`src/http/invitations.spec.ts\` and \`src/invitations/service.spec.ts\`. Reuse fixtures with a real test store.
|
|
49159
49339
|
|
|
49160
49340
|
#### Trade-offs
|
|
49161
49341
|
|
|
@@ -49178,7 +49358,7 @@ Email delivery can fail after persistence. Use existing queue retries and keep t
|
|
|
49178
49358
|
- [ ] Queue delivery after persistence, retry transient mail failures, and expose the pending state to owners.
|
|
49179
49359
|
- [ ] In \`src/http/invitations.spec.ts\`, send an owner invitation, accept as its recipient, and read back membership. Verify wrong-recipient, expired, and used-token requests leave state unchanged. Verify an email failure keeps the saved invitation pending.
|
|
49180
49360
|
- [ ] Validation
|
|
49181
|
-
- [ ] Run the
|
|
49361
|
+
- [ ] Run the application acceptance/rejection scenarios, then the service integration scenarios listed above.
|
|
49182
49362
|
- [ ] Run relevant lint and format checks. This example grants no commit or push permission.
|
|
49183
49363
|
- [ ] If execution authorizes commits and expects CI, commit the changes and confirm CI is green for that commit.
|
|
49184
49364
|
|
|
@@ -49209,8 +49389,6 @@ Readers should retain access to historical activity while the team changes stora
|
|
|
49209
49389
|
|
|
49210
49390
|
### Big Ideas
|
|
49211
49391
|
|
|
49212
|
-
Write to both stores temporarily, backfill older records with stable IDs, compare counts and ordering, then switch readers behind a reversible flag. Keep the legacy reader authoritative until the new store is verified.
|
|
49213
|
-
|
|
49214
49392
|
\`\`\`mermaid
|
|
49215
49393
|
flowchart LR
|
|
49216
49394
|
Writer["Activity writer"] --> Old["Legacy store"]
|
|
@@ -49250,34 +49428,36 @@ readSource = legacy | new # reversible; legacy remains default
|
|
|
49250
49428
|
|
|
49251
49429
|
#### Repo Changes
|
|
49252
49430
|
|
|
49253
|
-
Illustrative paths:
|
|
49431
|
+
Illustrative paths: \`[M]\` modified, \`[A]\` added, \`[D]\` deleted, \`[R]\` renamed. No files are removed or renamed. \`writer.ts\` and \`backfill.ts\` contain the largest edits.
|
|
49254
49432
|
|
|
49255
49433
|
\`\`\`text
|
|
49256
49434
|
infra/
|
|
49257
|
-
\u2514\u2500\u2500 activity-store.tf
|
|
49435
|
+
\u2514\u2500\u2500 [A] activity-store.tf store, credentials, write-failure metrics
|
|
49258
49436
|
src/
|
|
49259
49437
|
\u2514\u2500\u2500 activity/
|
|
49260
|
-
\u251C\u2500\u2500 writer.ts
|
|
49261
|
-
\u251C\u2500\u2500 backfill.ts
|
|
49262
|
-
\u251C\u2500\u2500 reader.ts
|
|
49263
|
-
\u251C\u2500\u2500 migration.spec.ts
|
|
49264
|
-
\u2514\u2500\u2500 history.spec.ts
|
|
49438
|
+
\u251C\u2500\u2500 [M] writer.ts dual writes and retries
|
|
49439
|
+
\u251C\u2500\u2500 [A] backfill.ts resumable batches and comparison
|
|
49440
|
+
\u251C\u2500\u2500 [M] reader.ts reversible read source
|
|
49441
|
+
\u251C\u2500\u2500 [A] migration.spec.ts public API parity and restart scenarios
|
|
49442
|
+
\u2514\u2500\u2500 [M] history.spec.ts application history across cutover/rollback
|
|
49265
49443
|
\`\`\`
|
|
49266
49444
|
|
|
49267
49445
|
#### Testing
|
|
49268
49446
|
|
|
49269
49447
|
\`\`\`text
|
|
49270
|
-
|
|
49271
|
-
\u2514\u2500\u2500 activity
|
|
49272
|
-
\u251C\u2500\u2500
|
|
49273
|
-
\u2514\u2500\u2500
|
|
49274
|
-
|
|
49275
|
-
\u2514\u2500\u2500
|
|
49276
|
-
\
|
|
49277
|
-
|
|
49448
|
+
src/
|
|
49449
|
+
\u2514\u2500\u2500 activity/
|
|
49450
|
+
\u251C\u2500\u2500 [M] history.spec.ts (application behavior)
|
|
49451
|
+
\u2502 \u2514\u2500\u2500 [A] describe activity history cutover
|
|
49452
|
+
\u2502 \u251C\u2500\u2500 [A] given dual writes, when paging history across cutover, then records and cursors match
|
|
49453
|
+
\u2502 \u2514\u2500\u2500 [A] given writes after cutover, when rolling back, then no events are lost
|
|
49454
|
+
\u2514\u2500\u2500 [A] migration.spec.ts (public module behavior)
|
|
49455
|
+
\u2514\u2500\u2500 [A] describe activity storage migration
|
|
49456
|
+
\u251C\u2500\u2500 [A] given a failed destination write, when retried, then one logical event exists in each store
|
|
49457
|
+
\u2514\u2500\u2500 [A] given an interrupted backfill, when resumed, then IDs and order match without duplicates
|
|
49278
49458
|
\`\`\`
|
|
49279
49459
|
|
|
49280
|
-
Use \`src/activity/history.spec.ts\` for application
|
|
49460
|
+
Use BDD-style nested \`given\`/\`when\`/\`then\` scenarios in \`src/activity/history.spec.ts\` for application behavior and \`src/activity/migration.spec.ts\` for public storage APIs with real test stores.
|
|
49281
49461
|
|
|
49282
49462
|
#### Trade-offs
|
|
49283
49463
|
|
|
@@ -49309,7 +49489,7 @@ Dual writes increase latency and allow partial failure. Record discrepancies and
|
|
|
49309
49489
|
- [ ] Extend application scenarios in \`src/activity/history.spec.ts\`: write and read paged history, switch stores, write again, and roll back. Assert the same visible history without lost events; do not assert private helper calls.
|
|
49310
49490
|
- [ ] Keep dual writes and monitor parity through the rollback window.
|
|
49311
49491
|
- [ ] Validation
|
|
49312
|
-
- [ ] Run the
|
|
49492
|
+
- [ ] Run the application cutover/rollback scenarios, then the storage integration scenarios listed above.
|
|
49313
49493
|
- [ ] Run relevant lint and format checks. This example grants no commit or push permission.
|
|
49314
49494
|
- [ ] If execution authorizes commits and expects CI, commit the changes and confirm CI is green for that commit.
|
|
49315
49495
|
|
|
@@ -49499,94 +49679,75 @@ var init_prd_onboarding = () => {};
|
|
|
49499
49679
|
var review_change_default = `# Review: invitation acceptance
|
|
49500
49680
|
|
|
49501
49681
|
- **Revision:** illustrative-change-17
|
|
49502
|
-
- **Intent:** Accept
|
|
49682
|
+
- **Intent:** Accept valid invitations without changing membership on rejection.
|
|
49503
49683
|
- **Reviewer:** Authored example, not an executed review.
|
|
49504
|
-
|
|
49505
|
-
This is a fictional example. A real review must use its runtime model name in attribution.
|
|
49684
|
+
- **Mode:** Normal, single model.
|
|
49506
49685
|
|
|
49507
49686
|
## Intent Delivery
|
|
49508
49687
|
|
|
49509
|
-
|
|
49688
|
+
Acceptance lacks a saved-membership check. See [request 2](#request-2).
|
|
49510
49689
|
|
|
49511
49690
|
## Readability
|
|
49512
49691
|
|
|
49513
|
-
|
|
49692
|
+
A query-like name hides a write. See [request 1](#request-1).
|
|
49514
49693
|
|
|
49515
49694
|
## Semantic Organization
|
|
49516
49695
|
|
|
49517
|
-
The handler maps
|
|
49696
|
+
The handler maps requests. The service owns acceptance. The store saves membership.
|
|
49518
49697
|
|
|
49519
49698
|
## Maintainability
|
|
49520
49699
|
|
|
49521
|
-
The
|
|
49700
|
+
The service reuses invitation status without adding duplicate state.
|
|
49522
49701
|
|
|
49523
49702
|
## Reliability/Testing
|
|
49524
49703
|
|
|
49525
|
-
|
|
49526
|
-
|
|
49527
|
-
Repeated setup and nested assertions hide the scenario in \`service.spec.ts:18\`. I suggest a fixture and separate blocks:
|
|
49704
|
+
See [request 2](#request-2).
|
|
49528
49705
|
|
|
49529
|
-
|
|
49530
|
-
describe('acceptInvitation', () => {
|
|
49531
|
-
test('rejects an expired invitation without adding membership', async () => {
|
|
49532
|
-
// Arrange
|
|
49533
|
-
const { service, members, recipient, expiredToken } = await invitationFixture()
|
|
49706
|
+
## Documentation
|
|
49534
49707
|
|
|
49535
|
-
|
|
49536
|
-
const acceptance = service.acceptInvitation(expiredToken, recipient.id)
|
|
49537
|
-
|
|
49538
|
-
// Assert
|
|
49539
|
-
await expect(acceptance).rejects.toThrow(InvitationExpiredError)
|
|
49540
|
-
expect(await members.list(recipient.id)).toEqual([])
|
|
49541
|
-
})
|
|
49542
|
-
})
|
|
49543
|
-
\`\`\`
|
|
49544
|
-
|
|
49545
|
-
The fixture creates a real test store. I recommend keeping the action and assertions visible and reusing shared setup.
|
|
49546
|
-
|
|
49547
|
-
## Repository Guidance
|
|
49548
|
-
|
|
49549
|
-
The fictional \`AGENTS.md\` requires Arrange/Act/Assert blocks and local helpers at the bottom. I suggest separating the mixed steps in \`service.spec.ts:18\`.
|
|
49708
|
+
The changed API comment explains token consumption.
|
|
49550
49709
|
|
|
49551
49710
|
## Performance
|
|
49552
49711
|
|
|
49553
|
-
|
|
49712
|
+
No material regression found by inspection. No performance measurements ran.
|
|
49554
49713
|
|
|
49555
49714
|
## Security
|
|
49556
49715
|
|
|
49557
|
-
|
|
49716
|
+
Not selected. No security audit is claimed.
|
|
49558
49717
|
|
|
49559
49718
|
## Change Requests
|
|
49560
49719
|
|
|
49561
|
-
###
|
|
49720
|
+
### Request 1
|
|
49562
49721
|
|
|
49563
49722
|
- **Status:** open
|
|
49564
|
-
- **Request:** \`loadInvitation\` also writes membership. I suggest
|
|
49723
|
+
- **Request:** \`src/invitations/service.ts:42\`: \`loadInvitation\` also writes membership. I suggest \`acceptInvitation\` so callers see the write.
|
|
49565
49724
|
|
|
49566
|
-
> Generated via [actual model
|
|
49725
|
+
> Generated via [actual runtime model; illustrative placeholder only]
|
|
49567
49726
|
|
|
49568
|
-
###
|
|
49727
|
+
### Request 2
|
|
49569
49728
|
|
|
49570
49729
|
- **Status:** open
|
|
49571
|
-
- **Request:**
|
|
49730
|
+
- **Request:** \`src/invitations/service.spec.ts:18\`: Helper tests do not establish saved membership. Let's test acceptance and rejection through the public API, then read membership back.
|
|
49572
49731
|
|
|
49573
|
-
> Generated via [actual model
|
|
49732
|
+
> Generated via [actual runtime model; illustrative placeholder only]
|
|
49574
49733
|
|
|
49575
49734
|
## Findings
|
|
49576
49735
|
|
|
49577
|
-
| Severity | Location
|
|
49578
|
-
|
|
|
49579
|
-
| consider | \`
|
|
49580
|
-
| consider | \`
|
|
49736
|
+
| Severity | Location | Request |
|
|
49737
|
+
| -------- | -------------------- | ----------------------- |
|
|
49738
|
+
| consider | \`service.ts:42\` | [Request 1](#request-1) |
|
|
49739
|
+
| consider | \`service.spec.ts:18\` | [Request 2](#request-2) |
|
|
49581
49740
|
|
|
49582
49741
|
## Overall Assessment
|
|
49583
49742
|
|
|
49584
|
-
|
|
49743
|
+
Address the two requests. No unrelated cleanup is needed.
|
|
49585
49744
|
|
|
49586
49745
|
## Verification and Limits
|
|
49587
49746
|
|
|
49588
|
-
- **Checks run:**
|
|
49589
|
-
- **Not verified:**
|
|
49747
|
+
- **Checks run:** None. This is a fictional example.
|
|
49748
|
+
- **Not verified:** Execution and real repository guidance.
|
|
49749
|
+
- **Rubric:** A real review links its filled rubric here.
|
|
49750
|
+
- **Council:** Not selected.
|
|
49590
49751
|
`;
|
|
49591
49752
|
var init_review_change = () => {};
|
|
49592
49753
|
|
|
@@ -49748,6 +49909,7 @@ var init_source = __esm(() => {
|
|
|
49748
49909
|
init_product_requirements_document();
|
|
49749
49910
|
init_agents();
|
|
49750
49911
|
init_code_review();
|
|
49912
|
+
init_code_review_rubric();
|
|
49751
49913
|
init_planning_intent();
|
|
49752
49914
|
init_ui_component_architecture();
|
|
49753
49915
|
init_pull_request_description();
|
|
@@ -49774,6 +49936,7 @@ var init_source = __esm(() => {
|
|
|
49774
49936
|
"product-requirements-document.md": product_requirements_document_default,
|
|
49775
49937
|
"agents.md": agents_default,
|
|
49776
49938
|
"code-review.md": code_review_default,
|
|
49939
|
+
"code-review-rubric.yaml": code_review_rubric_default,
|
|
49777
49940
|
"planning-intent.md": planning_intent_default,
|
|
49778
49941
|
"ui-component-architecture.md": ui_component_architecture_default,
|
|
49779
49942
|
"pull-request-description.md": pull_request_description_default,
|
|
@@ -49801,6 +49964,11 @@ var init_source = __esm(() => {
|
|
|
49801
49964
|
{ name: "product-requirements-document", description: "Product requirements document" },
|
|
49802
49965
|
{ name: "agents", description: "Concise repository rules for AGENTS.md" },
|
|
49803
49966
|
{ name: "code-review", description: "Thorough code review" },
|
|
49967
|
+
{
|
|
49968
|
+
name: "code-review-rubric",
|
|
49969
|
+
description: "YAML code review criteria and per-file results",
|
|
49970
|
+
asset: "code-review-rubric.yaml"
|
|
49971
|
+
},
|
|
49804
49972
|
{ name: "planning-intent", description: "Planning intent for a user to fill in" },
|
|
49805
49973
|
{ name: "ui-component-architecture", description: "UI component design and implementation" },
|
|
49806
49974
|
{ name: "pull-request-description", description: "Draft pull request description" },
|
|
@@ -49844,7 +50012,8 @@ class TemplateService {
|
|
|
49844
50012
|
return [...this.source.catalog];
|
|
49845
50013
|
}
|
|
49846
50014
|
async scaffoldFromTemplate(name, cwd, path, filename) {
|
|
49847
|
-
|
|
50015
|
+
const template = this.source.catalog.find((item) => item.name === name);
|
|
50016
|
+
if (!template) {
|
|
49848
50017
|
throw new UnknownTemplateError(`Unknown template: ${name}`);
|
|
49849
50018
|
}
|
|
49850
50019
|
if (!path.trim() || isAbsolute7(path)) {
|
|
@@ -49854,8 +50023,8 @@ class TemplateService {
|
|
|
49854
50023
|
throw new TemplateError("filename must be a single non-empty file name");
|
|
49855
50024
|
}
|
|
49856
50025
|
await this.installMissing();
|
|
49857
|
-
const installed = await resolvePath(this.home, join6(".difflab", "templates", `${name}.md`));
|
|
49858
|
-
const contents = await
|
|
50026
|
+
const installed = await resolvePath(this.home, join6(".difflab", "templates", template.asset ?? `${name}.md`));
|
|
50027
|
+
const contents = await readTemplate(installed);
|
|
49859
50028
|
const destination = path.startsWith(".difflab/") ? await this.projectDestination(cwd, path.slice(".difflab/".length), filename) : await ensurePathDirsExist(join6(path, filename), cwd);
|
|
49860
50029
|
try {
|
|
49861
50030
|
await createExclusive(destination, contents);
|
|
@@ -49888,7 +50057,7 @@ class TemplateService {
|
|
|
49888
50057
|
if ((await lstat7(destination)).isSymbolicLink()) {
|
|
49889
50058
|
throw new TemplateSourceError(`Installed template asset is a symlink: ${destination}`);
|
|
49890
50059
|
}
|
|
49891
|
-
await
|
|
50060
|
+
await readTemplate(destination);
|
|
49892
50061
|
} catch (error) {
|
|
49893
50062
|
if (!hasErrorCode(error, "ENOENT"))
|
|
49894
50063
|
throw error;
|
|
@@ -49898,7 +50067,7 @@ class TemplateService {
|
|
|
49898
50067
|
} catch (writeError) {
|
|
49899
50068
|
if (!hasErrorCode(writeError, "EEXIST"))
|
|
49900
50069
|
throw writeError;
|
|
49901
|
-
await
|
|
50070
|
+
await readTemplate(destination);
|
|
49902
50071
|
}
|
|
49903
50072
|
}
|
|
49904
50073
|
}
|
|
@@ -49916,7 +50085,7 @@ async function readSource(source, asset) {
|
|
|
49916
50085
|
throw new TemplateSourceError(`Cannot read template asset: ${asset}`, { cause: error });
|
|
49917
50086
|
}
|
|
49918
50087
|
}
|
|
49919
|
-
async function
|
|
50088
|
+
async function readTemplate(path) {
|
|
49920
50089
|
let handle;
|
|
49921
50090
|
try {
|
|
49922
50091
|
handle = await open3(path, constants2.O_RDONLY | constants2.O_NOFOLLOW);
|
|
@@ -49974,7 +50143,8 @@ var init_tools4 = __esm(() => {
|
|
|
49974
50143
|
init_service();
|
|
49975
50144
|
templateInfo = object({
|
|
49976
50145
|
name: string2(),
|
|
49977
|
-
description: string2()
|
|
50146
|
+
description: string2(),
|
|
50147
|
+
asset: string2().optional()
|
|
49978
50148
|
});
|
|
49979
50149
|
templateListOutput = object({ result: array(templateInfo) });
|
|
49980
50150
|
scaffoldOutput = object({
|
|
@@ -52366,7 +52536,7 @@ function createProgram(write = console.log, version = "0.1.0", options = {}) {
|
|
|
52366
52536
|
|
|
52367
52537
|
// src/index.ts
|
|
52368
52538
|
init_errors3();
|
|
52369
|
-
var version2 = "0.
|
|
52539
|
+
var version2 = "0.12.0";
|
|
52370
52540
|
try {
|
|
52371
52541
|
await createProgram(console.log, version2).parseAsync(process.argv);
|
|
52372
52542
|
} catch (error) {
|