@difflab/difflab-cli 0.11.0 → 0.13.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 +8 -4
- package/dist/index.js +157 -109
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -66,7 +66,7 @@ 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`, `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`,
|
|
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`, `poc-readme`, `hook-definition`, and `task`.
|
|
70
70
|
|
|
71
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.
|
|
72
72
|
|
|
@@ -74,11 +74,15 @@ Use `difflab-cli templates scaffold agents . AGENTS.md --cwd /absolute/project/p
|
|
|
74
74
|
|
|
75
75
|
On first use, missing bundled templates and filled examples are copied to `~/.difflab/templates` and `~/.difflab/templates/examples`. Edit the installed templates to customize future documents. Later runs add missing files but never replace existing ones, even after an upgrade. Examples are for reference, not selectable templates. Copying is literal: prompts and placeholders are not substituted. An unknown name, missing or invalid source, unsafe path, symlink, or existing destination causes an error; destination files are never overwritten. The target directory must remain inside `cwd` and the filename must be a single file name without separators. The one symlink exception is an initialized repository's `.difflab` link to its own user project store: `templates scaffold spec-driven-plan .difflab/plans/YYMMDD-name PLAN.md --cwd /absolute/repo` works in Git worktrees as well. To restore a bundled default, move your installed copy aside before listing again.
|
|
76
76
|
|
|
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.
|
|
77
|
+
The portable `skills/difflab-plan`, `skills/difflab-review`, `skills/difflab-flow`, `skills/difflab-hooks`, `skills/difflab-bdd`, `skills/difflab-writing-style`, `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.
|
|
78
78
|
|
|
79
|
-
The [plan authoring guide](../../skills/difflab-plan/references/authoring.md) requires component/process/artifact visuals, compact interfaces, and a
|
|
79
|
+
The [plan authoring guide](../../skills/difflab-plan/references/authoring.md) applies `difflab-writing-style` and `difflab-bdd`. It requires component/process/artifact visuals, compact interfaces, and a directory-grouped `[M/A/D/R]` repo tree at the start of `Consequences`. Add a `Testing` subsection with a behavior flowchart and a matching `[M/A/D/R]` BDD test tree (`given`/`when`/`then`) 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
80
|
|
|
81
|
-
The [review rubric](../../skills/difflab-review/references/rubric.md) follows
|
|
81
|
+
The [review rubric](../../skills/difflab-review/references/rubric.md) follows written `AGENTS.md` rules, `difflab-writing-style`, and `difflab-bdd`. 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 test suites against the component's behavior flowchart to propose BDD tree reorganizations (`given`/`when`/`then` with hoisted fixtures) when needed. 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 run in the current single agent without subagents or councils, keeping the selected frontier model regardless of vendor. `--adversarial` challenges all dimensions, including Security.
|
|
84
|
+
|
|
85
|
+
PR creation through `pr new`, create, open, or draft always scaffolds and fills the installed `pull-request-description` template before creating the request, then reads the saved body back. `pr merge` watches post-merge CI and then invokes `~/.difflab/hooks/on-merge/HOOK.md` via `difflab-hooks` when registered. `pr merge --squash` selects a native forge squash merge before the operation. These are Agent Skill requests, not CLI subcommands.
|
|
82
86
|
|
|
83
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.
|
|
84
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
|
|
48379
|
+
[Start with a directory-grouped file tree using \`[M]\` modified, \`[A]\` added, \`[D]\` deleted, and \`[R]\` renamed before changed entries, including tests. Apply \`/difflab-writing-style\`. Identify the largest edits in a short note. Use real inspected paths and label proposed files. State when nothing is removed.]
|
|
48380
48380
|
|
|
48381
48381
|
#### Testing
|
|
48382
48382
|
|
|
48383
|
-
[
|
|
48383
|
+
[Apply \`/difflab-bdd\`. First draw a Mermaid behavior flowchart showing context branches, state transitions, and converging intermediate states from the user's or caller's perspective. Then map the flowchart into a nested \`[M/A/D/R]\` BDD test tree starting with \`given <context>\` (or optional \`describe\`/\`feature\`), nesting \`when\` -> \`then\` as needed, collapsing single-outcome branches to \`when <action>, then <outcome>\`, and hoisting shared fixtures. Prioritize \`e2e\` > \`integration\` > \`unit\` and specify human-verifiable outputs (screenshots, replays, file dumps, snapshots, JSON outputs, or debug logs). Label skill checks without a harness as \`manual acceptance\`.]
|
|
48384
48384
|
|
|
48385
48385
|
#### Trade-offs
|
|
48386
48386
|
|
|
@@ -48662,9 +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]
|
|
48666
48667
|
|
|
48667
|
-
[Apply
|
|
48668
|
+
[Apply \`/difflab-writing-style\` and \`/difflab-bdd\`. 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.]
|
|
48668
48669
|
|
|
48669
48670
|
## Intent Delivery
|
|
48670
48671
|
|
|
@@ -48672,7 +48673,7 @@ var code_review_default = `# Review: [change or pull request]
|
|
|
48672
48673
|
|
|
48673
48674
|
## Readability
|
|
48674
48675
|
|
|
48675
|
-
[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.]
|
|
48676
48677
|
|
|
48677
48678
|
## Semantic Organization
|
|
48678
48679
|
|
|
@@ -48680,15 +48681,15 @@ var code_review_default = `# Review: [change or pull request]
|
|
|
48680
48681
|
|
|
48681
48682
|
## Maintainability
|
|
48682
48683
|
|
|
48683
|
-
[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.]
|
|
48684
48685
|
|
|
48685
48686
|
## Reliability/Testing
|
|
48686
48687
|
|
|
48687
|
-
[
|
|
48688
|
+
[Apply \`/difflab-bdd\`. Analyze tests against the component's behavior flowchart (converging state branches, \`e2e\` > \`integration\` > \`unit\`, and human-verifiable outputs such as screenshots, replays, file dumps, snapshots, JSON outputs, or debug logs). Propose a concrete \`[M/A/D/R]\` BDD test tree reorganization (\`given\` -> \`when\` -> \`then\` with hoisted fixtures) when tests are flat, repeat downstream assertions across converged states, or obscure setup. Flag tests that only verify external dependencies rather than the repository's source behavior. Report executed checks and limits honestly.]
|
|
48688
48689
|
|
|
48689
48690
|
## Documentation
|
|
48690
48691
|
|
|
48691
|
-
[Flag walls of text, complex language, and text that only restates the implementation. Require concise
|
|
48692
|
+
[Apply \`/difflab-writing-style\`. Flag walls of text, complex language, and text that only restates the implementation. Require concise \`/simple-english\` explanations, domain terminology, and Mermaid/Draw.io diagrams or \`[M/A/D/R]\` trees when visuals communicate structure or flow better than prose.]
|
|
48692
48693
|
|
|
48693
48694
|
## Performance
|
|
48694
48695
|
|
|
@@ -48696,11 +48697,11 @@ var code_review_default = `# Review: [change or pull request]
|
|
|
48696
48697
|
|
|
48697
48698
|
## Security
|
|
48698
48699
|
|
|
48699
|
-
[Optional:
|
|
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.]
|
|
48700
48701
|
|
|
48701
48702
|
## Change Requests
|
|
48702
48703
|
|
|
48703
|
-
|
|
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.
|
|
48704
48705
|
|
|
48705
48706
|
### [file:line \u2014 request]
|
|
48706
48707
|
|
|
@@ -48717,7 +48718,7 @@ Every generated comment and reply must use simple English and be as short as pos
|
|
|
48717
48718
|
|
|
48718
48719
|
| Severity | Location | Evidence and impact | Required change or question |
|
|
48719
48720
|
| --- | --- | --- | --- |
|
|
48720
|
-
| [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] |
|
|
48721
48722
|
|
|
48722
48723
|
## Overall Assessment
|
|
48723
48724
|
|
|
@@ -48733,16 +48734,15 @@ var init_code_review = () => {};
|
|
|
48733
48734
|
|
|
48734
48735
|
// templates/code-review-rubric.yaml
|
|
48735
48736
|
var code_review_rubric_default = `version: 1
|
|
48736
|
-
|
|
48737
|
-
|
|
48738
|
-
reasoning_effort: medium
|
|
48737
|
+
review_defaults:
|
|
48738
|
+
model_policy: retain-frontier
|
|
48739
48739
|
review:
|
|
48740
48740
|
base_revision: null
|
|
48741
48741
|
head_revision: null
|
|
48742
48742
|
working_tree: null
|
|
48743
48743
|
changed_files: []
|
|
48744
48744
|
exclusions: []
|
|
48745
|
-
|
|
48745
|
+
reviewers: []
|
|
48746
48746
|
sections:
|
|
48747
48747
|
- title: Intent Delivery
|
|
48748
48748
|
criteria:
|
|
@@ -48762,7 +48762,7 @@ sections:
|
|
|
48762
48762
|
scope: file
|
|
48763
48763
|
default_severity: consider
|
|
48764
48764
|
issue: >-
|
|
48765
|
-
Function or other names misrepresent behavior, hide side effects, or
|
|
48765
|
+
Function or other names misrepresent behavior, hide side effects, or violate written naming rules.
|
|
48766
48766
|
results: []
|
|
48767
48767
|
- id: readability.structure
|
|
48768
48768
|
scope: file
|
|
@@ -48779,7 +48779,7 @@ sections:
|
|
|
48779
48779
|
- id: organization.architecture
|
|
48780
48780
|
scope: review
|
|
48781
48781
|
default_severity: consider
|
|
48782
|
-
issue: Files or classes
|
|
48782
|
+
issue: Files or classes mix responsibilities, obscure ownership, or violate written architecture rules.
|
|
48783
48783
|
results: []
|
|
48784
48784
|
- id: organization.api-ergonomics
|
|
48785
48785
|
scope: applicable-file
|
|
@@ -48835,14 +48835,15 @@ sections:
|
|
|
48835
48835
|
- id: testing.application
|
|
48836
48836
|
scope: review
|
|
48837
48837
|
default_severity: consider
|
|
48838
|
-
issue:
|
|
48838
|
+
issue: >-
|
|
48839
|
+
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.
|
|
48839
48840
|
results: []
|
|
48840
48841
|
- id: testing.relevance
|
|
48841
48842
|
scope: applicable-file
|
|
48842
48843
|
applies_when: Added or modified test files.
|
|
48843
48844
|
default_severity: consider
|
|
48844
48845
|
issue: >-
|
|
48845
|
-
|
|
48846
|
+
Verbose unit tests pad coverage without proving real contracts, validate static asset or template structure, test the test apparatus itself, add regression tests for changes within the same changeset or for alpha projects without users, or only verify external dependency behavior.
|
|
48846
48847
|
results: []
|
|
48847
48848
|
- id: testing.names
|
|
48848
48849
|
scope: applicable-file
|
|
@@ -48856,7 +48857,7 @@ sections:
|
|
|
48856
48857
|
applies_when: Added or modified test files.
|
|
48857
48858
|
default_severity: consider
|
|
48858
48859
|
issue: >-
|
|
48859
|
-
Test
|
|
48860
|
+
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.
|
|
48860
48861
|
results: []
|
|
48861
48862
|
- id: testing.fixtures
|
|
48862
48863
|
scope: applicable-file
|
|
@@ -48900,8 +48901,6 @@ sections:
|
|
|
48900
48901
|
default_severity: blocking
|
|
48901
48902
|
issue: The change exposes secrets or breaks authorization or a trust boundary.
|
|
48902
48903
|
results: []
|
|
48903
|
-
worker:
|
|
48904
|
-
reasoning_effort: high
|
|
48905
48904
|
`;
|
|
48906
48905
|
var init_code_review_rubric = () => {};
|
|
48907
48906
|
|
|
@@ -49245,6 +49244,46 @@ The \`base_commit\` is the full SHA of \`origin/main\` when this branch was crea
|
|
|
49245
49244
|
`;
|
|
49246
49245
|
var init_poc_readme = () => {};
|
|
49247
49246
|
|
|
49247
|
+
// templates/hook-definition.md
|
|
49248
|
+
var hook_definition_default = `# {{name}}
|
|
49249
|
+
|
|
49250
|
+
## Trigger
|
|
49251
|
+
|
|
49252
|
+
{{trigger}}
|
|
49253
|
+
|
|
49254
|
+
## Action
|
|
49255
|
+
|
|
49256
|
+
- Handler: \`{{handler}}\`
|
|
49257
|
+
- Requires: \`{{requires}}\`
|
|
49258
|
+
- Receives: \`{{receives}}\`
|
|
49259
|
+
|
|
49260
|
+
## Instructions
|
|
49261
|
+
|
|
49262
|
+
{{instructions}}
|
|
49263
|
+
`;
|
|
49264
|
+
var init_hook_definition = () => {};
|
|
49265
|
+
|
|
49266
|
+
// templates/task.md
|
|
49267
|
+
var task_default = `# [Task title]
|
|
49268
|
+
|
|
49269
|
+
## Objective
|
|
49270
|
+
|
|
49271
|
+
[One-line description of what needs to be done.]
|
|
49272
|
+
|
|
49273
|
+
## Context
|
|
49274
|
+
|
|
49275
|
+
[Relevant background written using \`/difflab-writing-style\`, kept as terse as possible. Link to relevant architecture docs instead of repeating them. For a bug ticket, describe only the observable issue and impact; do not propose a solution.]
|
|
49276
|
+
|
|
49277
|
+
## Technical Approach
|
|
49278
|
+
|
|
49279
|
+
_To be completed by the person doing the work._
|
|
49280
|
+
|
|
49281
|
+
## References
|
|
49282
|
+
|
|
49283
|
+
- [Relevant links to wikis, architecture docs, tickets, external resources, CI logs, or incident portals.]
|
|
49284
|
+
`;
|
|
49285
|
+
var init_task = () => {};
|
|
49286
|
+
|
|
49248
49287
|
// templates/examples/plan-feature.md
|
|
49249
49288
|
var plan_feature_default = `# Invite teammates to a project
|
|
49250
49289
|
|
|
@@ -49266,8 +49305,6 @@ Project owners need to invite teammates without sharing credentials. Recipients
|
|
|
49266
49305
|
|
|
49267
49306
|
### Big Ideas
|
|
49268
49307
|
|
|
49269
|
-
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.
|
|
49270
|
-
|
|
49271
49308
|
\`\`\`mermaid
|
|
49272
49309
|
flowchart LR
|
|
49273
49310
|
HTTP["HTTP handler"] --> Service["Invitation service<br/>eligibility and acceptance"]
|
|
@@ -49275,7 +49312,7 @@ flowchart LR
|
|
|
49275
49312
|
Service --> Queue["Existing mail queue"]
|
|
49276
49313
|
\`\`\`
|
|
49277
49314
|
|
|
49278
|
-
|
|
49315
|
+
Store only the token hash. Save before queueing delivery. An email outage must not lose the invitation.
|
|
49279
49316
|
|
|
49280
49317
|
\`\`\`mermaid
|
|
49281
49318
|
flowchart TD
|
|
@@ -49305,34 +49342,50 @@ Never log raw tokens. Apply the existing request rate limit to creation; do not
|
|
|
49305
49342
|
|
|
49306
49343
|
#### Repo Changes
|
|
49307
49344
|
|
|
49308
|
-
Illustrative paths:
|
|
49345
|
+
Illustrative paths: \`[M]\` modified, \`[A]\` added, \`[D]\` deleted, \`[R]\` renamed. No files are removed or renamed. \`service.ts\` contains the largest edits.
|
|
49309
49346
|
|
|
49310
49347
|
\`\`\`text
|
|
49311
49348
|
src/
|
|
49312
49349
|
\u251C\u2500\u2500 invitations/
|
|
49313
|
-
\u2502 \u251C\u2500\u2500 store.ts
|
|
49314
|
-
\u2502 \u251C\u2500\u2500 service.ts
|
|
49315
|
-
\u2502 \u2514\u2500\u2500 service.spec.ts
|
|
49350
|
+
\u2502 \u251C\u2500\u2500 [A] store.ts persistence and transaction
|
|
49351
|
+
\u2502 \u251C\u2500\u2500 [A] service.ts invitation policy
|
|
49352
|
+
\u2502 \u2514\u2500\u2500 [A] service.spec.ts public API with real test store
|
|
49316
49353
|
\u2514\u2500\u2500 http/
|
|
49317
|
-
\u251C\u2500\u2500 routes.ts
|
|
49318
|
-
\u251C\u2500\u2500 invitations.ts
|
|
49319
|
-
\u2514\u2500\u2500 invitations.spec.ts
|
|
49354
|
+
\u251C\u2500\u2500 [M] routes.ts register invitation handlers
|
|
49355
|
+
\u251C\u2500\u2500 [A] invitations.ts transport and authorization
|
|
49356
|
+
\u2514\u2500\u2500 [A] invitations.spec.ts application request scenarios
|
|
49320
49357
|
\`\`\`
|
|
49321
49358
|
|
|
49322
49359
|
#### Testing
|
|
49323
49360
|
|
|
49361
|
+
\`\`\`mermaid
|
|
49362
|
+
flowchart TD
|
|
49363
|
+
Invite["Owner creates invitation"] --> Saved["State: Pending invitation saved<br/>(even if email queue fails)"]
|
|
49364
|
+
Saved --> Accept["Recipient submits token"]
|
|
49365
|
+
Accept --> Eligible{"Intended recipient,<br/>unused & unexpired?"}
|
|
49366
|
+
Eligible -->|"no"| Reject["Reject; membership & token unchanged"]
|
|
49367
|
+
Eligible -->|"yes"| Tx["Consume token + add member"]
|
|
49368
|
+
Tx -->|"tx fails"| Rollback["Roll back membership & token"]
|
|
49369
|
+
Tx -->|"tx succeeds"| Member["Return active membership"]
|
|
49370
|
+
\`\`\`
|
|
49371
|
+
|
|
49324
49372
|
\`\`\`text
|
|
49325
|
-
|
|
49326
|
-
\
|
|
49327
|
-
|
|
49328
|
-
|
|
49329
|
-
|
|
49330
|
-
\u2514\u2500\u2500
|
|
49331
|
-
|
|
49332
|
-
\u2514\u2500\u2500
|
|
49373
|
+
src/
|
|
49374
|
+
\u251C\u2500\u2500 http/
|
|
49375
|
+
\u2502 \u2514\u2500\u2500 [A] invitations.spec.ts (application behavior)
|
|
49376
|
+
\u2502 \u2514\u2500\u2500 [A] given a pending owner invitation
|
|
49377
|
+
\u2502 \u251C\u2500\u2500 [A] when the intended recipient accepts, then membership appears in JSON response
|
|
49378
|
+
\u2502 \u2514\u2500\u2500 [A] when a wrong recipient or expired/used token is submitted, then it rejects without changing state
|
|
49379
|
+
\u2514\u2500\u2500 invitations/
|
|
49380
|
+
\u2514\u2500\u2500 [A] service.spec.ts (public module behavior)
|
|
49381
|
+
\u251C\u2500\u2500 [A] given an email queue failure, when creating an invitation, then the saved invitation stays pending for retry
|
|
49382
|
+
\u2514\u2500\u2500 [A] given a pending invitation (converged state)
|
|
49383
|
+
\u2514\u2500\u2500 [A] when the database transaction fails during acceptance
|
|
49384
|
+
\u251C\u2500\u2500 [A] then membership changes roll back
|
|
49385
|
+
\u2514\u2500\u2500 [A] then the invitation token remains unconsumed
|
|
49333
49386
|
\`\`\`
|
|
49334
49387
|
|
|
49335
|
-
Use
|
|
49388
|
+
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.
|
|
49336
49389
|
|
|
49337
49390
|
#### Trade-offs
|
|
49338
49391
|
|
|
@@ -49355,7 +49408,7 @@ Email delivery can fail after persistence. Use existing queue retries and keep t
|
|
|
49355
49408
|
- [ ] Queue delivery after persistence, retry transient mail failures, and expose the pending state to owners.
|
|
49356
49409
|
- [ ] 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.
|
|
49357
49410
|
- [ ] Validation
|
|
49358
|
-
- [ ] Run the
|
|
49411
|
+
- [ ] Run the application acceptance/rejection scenarios, then the service integration scenarios listed above.
|
|
49359
49412
|
- [ ] Run relevant lint and format checks. This example grants no commit or push permission.
|
|
49360
49413
|
- [ ] If execution authorizes commits and expects CI, commit the changes and confirm CI is green for that commit.
|
|
49361
49414
|
|
|
@@ -49386,8 +49439,6 @@ Readers should retain access to historical activity while the team changes stora
|
|
|
49386
49439
|
|
|
49387
49440
|
### Big Ideas
|
|
49388
49441
|
|
|
49389
|
-
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.
|
|
49390
|
-
|
|
49391
49442
|
\`\`\`mermaid
|
|
49392
49443
|
flowchart LR
|
|
49393
49444
|
Writer["Activity writer"] --> Old["Legacy store"]
|
|
@@ -49427,34 +49478,45 @@ readSource = legacy | new # reversible; legacy remains default
|
|
|
49427
49478
|
|
|
49428
49479
|
#### Repo Changes
|
|
49429
49480
|
|
|
49430
|
-
Illustrative paths:
|
|
49481
|
+
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.
|
|
49431
49482
|
|
|
49432
49483
|
\`\`\`text
|
|
49433
49484
|
infra/
|
|
49434
|
-
\u2514\u2500\u2500 activity-store.tf
|
|
49485
|
+
\u2514\u2500\u2500 [A] activity-store.tf store, credentials, write-failure metrics
|
|
49435
49486
|
src/
|
|
49436
49487
|
\u2514\u2500\u2500 activity/
|
|
49437
|
-
\u251C\u2500\u2500 writer.ts
|
|
49438
|
-
\u251C\u2500\u2500 backfill.ts
|
|
49439
|
-
\u251C\u2500\u2500 reader.ts
|
|
49440
|
-
\u251C\u2500\u2500 migration.spec.ts
|
|
49441
|
-
\u2514\u2500\u2500 history.spec.ts
|
|
49488
|
+
\u251C\u2500\u2500 [M] writer.ts dual writes and retries
|
|
49489
|
+
\u251C\u2500\u2500 [A] backfill.ts resumable batches and comparison
|
|
49490
|
+
\u251C\u2500\u2500 [M] reader.ts reversible read source
|
|
49491
|
+
\u251C\u2500\u2500 [A] migration.spec.ts public API parity and restart scenarios
|
|
49492
|
+
\u2514\u2500\u2500 [M] history.spec.ts application history across cutover/rollback
|
|
49442
49493
|
\`\`\`
|
|
49443
49494
|
|
|
49444
49495
|
#### Testing
|
|
49445
49496
|
|
|
49497
|
+
\`\`\`mermaid
|
|
49498
|
+
flowchart TD
|
|
49499
|
+
Write["writeActivity(event)"] --> Dual["Dual write with stable ID"]
|
|
49500
|
+
Dual -->|"destination fails"| Retry["Retry failed store"] --> Parity["State: Both stores hold identical events"]
|
|
49501
|
+
Backfill["Interrupted backfill"] --> Resume["Resume batch"] --> Parity
|
|
49502
|
+
Parity --> Cutover["Switch read flag to new store"]
|
|
49503
|
+
Cutover --> ReadCutover["Page history across cutover"]
|
|
49504
|
+
Cutover --> Rollback["Write post-cutover events, then roll back flag"]
|
|
49505
|
+
\`\`\`
|
|
49506
|
+
|
|
49446
49507
|
\`\`\`text
|
|
49447
|
-
|
|
49448
|
-
\u2514\u2500\u2500 activity
|
|
49449
|
-
\u251C\u2500\u2500
|
|
49450
|
-
\u2514\u2500\u2500
|
|
49451
|
-
|
|
49452
|
-
\u2514\u2500\u2500
|
|
49453
|
-
\
|
|
49454
|
-
|
|
49508
|
+
src/
|
|
49509
|
+
\u2514\u2500\u2500 activity/
|
|
49510
|
+
\u251C\u2500\u2500 [M] history.spec.ts (application behavior)
|
|
49511
|
+
\u2502 \u2514\u2500\u2500 [A] given dual-written stores at parity (converged state)
|
|
49512
|
+
\u2502 \u251C\u2500\u2500 [A] when paging history across reader cutover, then records and cursors match
|
|
49513
|
+
\u2502 \u2514\u2500\u2500 [A] when rolling back the reader after new writes, then no events are lost
|
|
49514
|
+
\u2514\u2500\u2500 [A] migration.spec.ts (public module behavior)
|
|
49515
|
+
\u251C\u2500\u2500 [A] given a failed destination write, when retried, then one logical event exists in each store
|
|
49516
|
+
\u2514\u2500\u2500 [A] given an interrupted backfill batch, when resumed, then IDs and order match without duplicates
|
|
49455
49517
|
\`\`\`
|
|
49456
49518
|
|
|
49457
|
-
Use \`src/activity/history.spec.ts\` for application
|
|
49519
|
+
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.
|
|
49458
49520
|
|
|
49459
49521
|
#### Trade-offs
|
|
49460
49522
|
|
|
@@ -49486,7 +49548,7 @@ Dual writes increase latency and allow partial failure. Record discrepancies and
|
|
|
49486
49548
|
- [ ] 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.
|
|
49487
49549
|
- [ ] Keep dual writes and monitor parity through the rollback window.
|
|
49488
49550
|
- [ ] Validation
|
|
49489
|
-
- [ ] Run the
|
|
49551
|
+
- [ ] Run the application cutover/rollback scenarios, then the storage integration scenarios listed above.
|
|
49490
49552
|
- [ ] Run relevant lint and format checks. This example grants no commit or push permission.
|
|
49491
49553
|
- [ ] If execution authorizes commits and expects CI, commit the changes and confirm CI is green for that commit.
|
|
49492
49554
|
|
|
@@ -49676,94 +49738,74 @@ var init_prd_onboarding = () => {};
|
|
|
49676
49738
|
var review_change_default = `# Review: invitation acceptance
|
|
49677
49739
|
|
|
49678
49740
|
- **Revision:** illustrative-change-17
|
|
49679
|
-
- **Intent:** Accept
|
|
49741
|
+
- **Intent:** Accept valid invitations without changing membership on rejection.
|
|
49680
49742
|
- **Reviewer:** Authored example, not an executed review.
|
|
49681
|
-
|
|
49682
|
-
This is a fictional example. A real review must use its runtime model name in attribution.
|
|
49743
|
+
- **Mode:** Normal, single model.
|
|
49683
49744
|
|
|
49684
49745
|
## Intent Delivery
|
|
49685
49746
|
|
|
49686
|
-
|
|
49747
|
+
Acceptance lacks a saved-membership check. See [request 2](#request-2).
|
|
49687
49748
|
|
|
49688
49749
|
## Readability
|
|
49689
49750
|
|
|
49690
|
-
|
|
49751
|
+
A query-like name hides a write. See [request 1](#request-1).
|
|
49691
49752
|
|
|
49692
49753
|
## Semantic Organization
|
|
49693
49754
|
|
|
49694
|
-
The handler maps
|
|
49755
|
+
The handler maps requests. The service owns acceptance. The store saves membership.
|
|
49695
49756
|
|
|
49696
49757
|
## Maintainability
|
|
49697
49758
|
|
|
49698
|
-
The
|
|
49759
|
+
The service reuses invitation status without adding duplicate state.
|
|
49699
49760
|
|
|
49700
49761
|
## Reliability/Testing
|
|
49701
49762
|
|
|
49702
|
-
|
|
49703
|
-
|
|
49704
|
-
Repeated setup and nested assertions hide the scenario in \`service.spec.ts:18\`. I suggest a fixture and separate blocks:
|
|
49763
|
+
See [request 2](#request-2).
|
|
49705
49764
|
|
|
49706
|
-
|
|
49707
|
-
describe('acceptInvitation', () => {
|
|
49708
|
-
test('rejects an expired invitation without adding membership', async () => {
|
|
49709
|
-
// Arrange
|
|
49710
|
-
const { service, members, recipient, expiredToken } = await invitationFixture()
|
|
49711
|
-
|
|
49712
|
-
// Act
|
|
49713
|
-
const acceptance = service.acceptInvitation(expiredToken, recipient.id)
|
|
49714
|
-
|
|
49715
|
-
// Assert
|
|
49716
|
-
await expect(acceptance).rejects.toThrow(InvitationExpiredError)
|
|
49717
|
-
expect(await members.list(recipient.id)).toEqual([])
|
|
49718
|
-
})
|
|
49719
|
-
})
|
|
49720
|
-
\`\`\`
|
|
49721
|
-
|
|
49722
|
-
The fixture creates a real test store. I recommend keeping the action and assertions visible and reusing shared setup.
|
|
49723
|
-
|
|
49724
|
-
## Repository Guidance
|
|
49765
|
+
## Documentation
|
|
49725
49766
|
|
|
49726
|
-
The
|
|
49767
|
+
The changed API comment explains token consumption.
|
|
49727
49768
|
|
|
49728
49769
|
## Performance
|
|
49729
49770
|
|
|
49730
|
-
|
|
49771
|
+
No material regression found by inspection. No performance measurements ran.
|
|
49731
49772
|
|
|
49732
49773
|
## Security
|
|
49733
49774
|
|
|
49734
|
-
|
|
49775
|
+
Not selected. No security audit is claimed.
|
|
49735
49776
|
|
|
49736
49777
|
## Change Requests
|
|
49737
49778
|
|
|
49738
|
-
###
|
|
49779
|
+
### Request 1
|
|
49739
49780
|
|
|
49740
49781
|
- **Status:** open
|
|
49741
|
-
- **Request:** \`loadInvitation\` also writes membership. I suggest
|
|
49782
|
+
- **Request:** \`src/invitations/service.ts:42\`: \`loadInvitation\` also writes membership. I suggest \`acceptInvitation\` so callers see the write.
|
|
49742
49783
|
|
|
49743
|
-
> Generated via [actual model
|
|
49784
|
+
> Generated via [actual runtime model; illustrative placeholder only]
|
|
49744
49785
|
|
|
49745
|
-
###
|
|
49786
|
+
### Request 2
|
|
49746
49787
|
|
|
49747
49788
|
- **Status:** open
|
|
49748
|
-
- **Request:**
|
|
49789
|
+
- **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.
|
|
49749
49790
|
|
|
49750
|
-
> Generated via [actual model
|
|
49791
|
+
> Generated via [actual runtime model; illustrative placeholder only]
|
|
49751
49792
|
|
|
49752
49793
|
## Findings
|
|
49753
49794
|
|
|
49754
|
-
| Severity | Location
|
|
49755
|
-
|
|
|
49756
|
-
| consider | \`
|
|
49757
|
-
| consider | \`
|
|
49795
|
+
| Severity | Location | Request |
|
|
49796
|
+
| -------- | -------------------- | ----------------------- |
|
|
49797
|
+
| consider | \`service.ts:42\` | [Request 1](#request-1) |
|
|
49798
|
+
| consider | \`service.spec.ts:18\` | [Request 2](#request-2) |
|
|
49758
49799
|
|
|
49759
49800
|
## Overall Assessment
|
|
49760
49801
|
|
|
49761
|
-
|
|
49802
|
+
Address the two requests. No unrelated cleanup is needed.
|
|
49762
49803
|
|
|
49763
49804
|
## Verification and Limits
|
|
49764
49805
|
|
|
49765
|
-
- **Checks run:**
|
|
49766
|
-
- **Not verified:**
|
|
49806
|
+
- **Checks run:** None. This is a fictional example.
|
|
49807
|
+
- **Not verified:** Execution and real repository guidance.
|
|
49808
|
+
- **Rubric:** A real review links its filled rubric here.
|
|
49767
49809
|
`;
|
|
49768
49810
|
var init_review_change = () => {};
|
|
49769
49811
|
|
|
@@ -49935,6 +49977,8 @@ var init_source = __esm(() => {
|
|
|
49935
49977
|
init_exploration_research();
|
|
49936
49978
|
init_exploration_proposal();
|
|
49937
49979
|
init_poc_readme();
|
|
49980
|
+
init_hook_definition();
|
|
49981
|
+
init_task();
|
|
49938
49982
|
init_plan_feature();
|
|
49939
49983
|
init_plan_migration();
|
|
49940
49984
|
init_design_service();
|
|
@@ -49962,6 +50006,8 @@ var init_source = __esm(() => {
|
|
|
49962
50006
|
"exploration-research.md": exploration_research_default,
|
|
49963
50007
|
"exploration-proposal.md": exploration_proposal_default,
|
|
49964
50008
|
"poc-readme.md": poc_readme_default,
|
|
50009
|
+
"hook-definition.md": hook_definition_default,
|
|
50010
|
+
"task.md": task_default,
|
|
49965
50011
|
"examples/plan-feature.md": plan_feature_default,
|
|
49966
50012
|
"examples/plan-migration.md": plan_migration_default,
|
|
49967
50013
|
"examples/design-service.md": design_service_default,
|
|
@@ -49993,7 +50039,9 @@ var init_source = __esm(() => {
|
|
|
49993
50039
|
{ name: "exploration-summary", description: "Source-grounded technical exploration summary" },
|
|
49994
50040
|
{ name: "exploration-research", description: "Technical exploration research notes" },
|
|
49995
50041
|
{ name: "exploration-proposal", description: "Optional technical exploration approach" },
|
|
49996
|
-
{ name: "poc-readme", description: "Disposable proof-of-concept branch README" }
|
|
50042
|
+
{ name: "poc-readme", description: "Disposable proof-of-concept branch README" },
|
|
50043
|
+
{ name: "hook-definition", description: "Reusable global Agent Skill hook definition" },
|
|
50044
|
+
{ name: "task", description: "Terse task or bug ticket with objective, context, and references" }
|
|
49997
50045
|
];
|
|
49998
50046
|
embeddedSource = {
|
|
49999
50047
|
catalog,
|
|
@@ -52552,7 +52600,7 @@ function createProgram(write = console.log, version = "0.1.0", options = {}) {
|
|
|
52552
52600
|
|
|
52553
52601
|
// src/index.ts
|
|
52554
52602
|
init_errors3();
|
|
52555
|
-
var version2 = "0.
|
|
52603
|
+
var version2 = "0.13.0";
|
|
52556
52604
|
try {
|
|
52557
52605
|
await createProgram(console.log, version2).parseAsync(process.argv);
|
|
52558
52606
|
} catch (error) {
|