@difflab/difflab-cli 0.12.0 → 0.13.1
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 +6 -6
- package/dist/index.js +217 -127
- package/package.json +2 -2
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,15 +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 written `AGENTS.md` rules and
|
|
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
82
|
|
|
83
|
-
Reviews
|
|
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
84
|
|
|
85
|
-
PR creation through `pr new`, create, open, or draft
|
|
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.
|
|
86
86
|
|
|
87
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.
|
|
88
88
|
|
package/dist/index.js
CHANGED
|
@@ -12497,7 +12497,7 @@ var init_migration = __esm(() => {
|
|
|
12497
12497
|
init_migrator();
|
|
12498
12498
|
});
|
|
12499
12499
|
|
|
12500
|
-
// ../../libs/difflab-db/src/migrations.ts
|
|
12500
|
+
// ../../libs/difflab-db-legacy/src/migrations.ts
|
|
12501
12501
|
async function migrate(db) {
|
|
12502
12502
|
const { error } = await new Migrator({ db, provider }).migrateToLatest();
|
|
12503
12503
|
if (error)
|
|
@@ -12696,7 +12696,7 @@ var init_normal = __esm(() => {
|
|
|
12696
12696
|
};
|
|
12697
12697
|
});
|
|
12698
12698
|
|
|
12699
|
-
// ../../libs/difflab-db/src/retry.ts
|
|
12699
|
+
// ../../libs/difflab-db-legacy/src/retry.ts
|
|
12700
12700
|
async function retryDatabaseOperation(work, retryable = isSqliteContention) {
|
|
12701
12701
|
for (let attempt = 1;; attempt++) {
|
|
12702
12702
|
try {
|
|
@@ -12726,7 +12726,7 @@ function errorChain(error) {
|
|
|
12726
12726
|
}
|
|
12727
12727
|
var maxAttempts = 10;
|
|
12728
12728
|
|
|
12729
|
-
// ../../libs/difflab-db/src/registry.ts
|
|
12729
|
+
// ../../libs/difflab-db-legacy/src/registry.ts
|
|
12730
12730
|
import { lstat } from "fs/promises";
|
|
12731
12731
|
import { resolve } from "path";
|
|
12732
12732
|
async function withDatabaseAccess(path, work) {
|
|
@@ -19227,7 +19227,7 @@ var init_zod = __esm(() => {
|
|
|
19227
19227
|
init_external();
|
|
19228
19228
|
});
|
|
19229
19229
|
|
|
19230
|
-
// ../../libs/difflab-db/src/entities/repository.ts
|
|
19230
|
+
// ../../libs/difflab-db-legacy/src/entities/repository.ts
|
|
19231
19231
|
var repositorySchema, validateRepository = (value) => repositorySchema.parse(value);
|
|
19232
19232
|
var init_repository = __esm(() => {
|
|
19233
19233
|
init_zod();
|
|
@@ -19239,7 +19239,7 @@ var init_repository = __esm(() => {
|
|
|
19239
19239
|
});
|
|
19240
19240
|
});
|
|
19241
19241
|
|
|
19242
|
-
// ../../libs/difflab-db/src/entities/project.ts
|
|
19242
|
+
// ../../libs/difflab-db-legacy/src/entities/project.ts
|
|
19243
19243
|
var projectSchema, validateProject = (value) => projectSchema.parse(value);
|
|
19244
19244
|
var init_project = __esm(() => {
|
|
19245
19245
|
init_zod();
|
|
@@ -19251,7 +19251,7 @@ var init_project = __esm(() => {
|
|
|
19251
19251
|
});
|
|
19252
19252
|
});
|
|
19253
19253
|
|
|
19254
|
-
// ../../libs/difflab-db/src/queries/projects.ts
|
|
19254
|
+
// ../../libs/difflab-db-legacy/src/queries/projects.ts
|
|
19255
19255
|
import { randomUUID } from "crypto";
|
|
19256
19256
|
function validateProjectKey(key) {
|
|
19257
19257
|
const normalized = key.trim().toUpperCase();
|
|
@@ -19355,7 +19355,7 @@ var init_projects = __esm(() => {
|
|
|
19355
19355
|
};
|
|
19356
19356
|
});
|
|
19357
19357
|
|
|
19358
|
-
// ../../libs/difflab-db/src/queries/repositories.ts
|
|
19358
|
+
// ../../libs/difflab-db-legacy/src/queries/repositories.ts
|
|
19359
19359
|
import { randomUUID as randomUUID2 } from "crypto";
|
|
19360
19360
|
function createRepositoryQueries(db, readonly, dbPath) {
|
|
19361
19361
|
return {
|
|
@@ -19412,7 +19412,7 @@ var init_repositories = __esm(() => {
|
|
|
19412
19412
|
init_projects();
|
|
19413
19413
|
});
|
|
19414
19414
|
|
|
19415
|
-
// ../../libs/difflab-db/src/index.ts
|
|
19415
|
+
// ../../libs/difflab-db-legacy/src/index.ts
|
|
19416
19416
|
async function createDifflabDb(dbPath, options = {}) {
|
|
19417
19417
|
const readonly = options.readonly ?? false;
|
|
19418
19418
|
const db = await openDatabase(dbPath, readonly);
|
|
@@ -48351,44 +48351,47 @@ var spec_driven_plan_default = `# [Outcome to deliver]
|
|
|
48351
48351
|
|
|
48352
48352
|
## Intent
|
|
48353
48353
|
|
|
48354
|
-
[
|
|
48354
|
+
[State who needs this change, what becomes possible afterward, and why it matters now.]
|
|
48355
48355
|
|
|
48356
48356
|
## Requirements
|
|
48357
48357
|
|
|
48358
|
-
-
|
|
48359
|
-
|
|
48358
|
+
[List observable behavioral capabilities and performance, security, cost, isolation, and reliability characteristics from a client, caller, or end-user perspective. Use plain bullets without \`FR\` or \`NFR\` prefixes. Put internal types, function names, CLI flags, configuration internals, file layouts, and code-style rules in Design and Phases.]
|
|
48359
|
+
|
|
48360
|
+
- [Observable client or end-user behavior and how to make sure that it works.]
|
|
48361
|
+
- [Observable performance, security, cost, isolation, or reliability characteristic.]
|
|
48362
|
+
- [Explicit boundaries and non-goals.]
|
|
48360
48363
|
|
|
48361
48364
|
## Design
|
|
48362
48365
|
|
|
48363
48366
|
### Big Ideas
|
|
48364
48367
|
|
|
48365
|
-
[Lead with compact diagrams.
|
|
48368
|
+
[Lead with compact Mermaid diagrams or fenced trees. Drop prose when a diagram shows the structure or flow. Show component relationships with a component diagram, processes with a flowchart, and file artifacts with a tree. Keep decisions, responsibilities, invariants, and failure behavior beside the visual. Draw only affected parts, and include enough detail to execute without the original chat.]
|
|
48366
48369
|
|
|
48367
48370
|
### Infrastructure Changes
|
|
48368
48371
|
|
|
48369
|
-
[
|
|
48372
|
+
[List hosting, service, deployment, network, or managed-resource changes. Put new source modules in Repo Changes. If no infrastructure changes, write N/A.]
|
|
48370
48373
|
|
|
48371
48374
|
### Interfaces
|
|
48372
48375
|
|
|
48373
|
-
[
|
|
48376
|
+
[Show changed public interactions, contracts, and failure results with compact commands, signatures, code, or pseudocode. Keep implementation steps in Phases.]
|
|
48374
48377
|
|
|
48375
48378
|
### Consequences
|
|
48376
48379
|
|
|
48377
48380
|
#### Repo Changes
|
|
48378
48381
|
|
|
48379
|
-
[
|
|
48382
|
+
[Draw a directory-grouped file tree with \`[M]\` modified, \`[A]\` added, \`[D]\` deleted, and \`[R]\` renamed markers. Apply \`/difflab-writing-style\`. Use real paths for existing files, label new files, and note the largest edits. If no files are removed, state that explicitly.]
|
|
48380
48383
|
|
|
48381
48384
|
#### Testing
|
|
48382
48385
|
|
|
48383
|
-
[
|
|
48386
|
+
[Apply \`/difflab-bdd\`. Draw a Mermaid behavior flowchart from the user or caller perspective with context branches, state transitions, and converging states. Map the flowchart to a nested \`[M/A/D/R]\` BDD test tree starting at \`given <context>\` with \`when\` and \`then\` clauses. Collapse single-outcome branches to \`when <action>, then <outcome>\`, and hoist shared fixtures. Prioritize \`e2e\` over \`integration\` over \`unit\`, and name human-verifiable outputs such as screenshots, snapshots, JSON payloads, or logs. If a skill change has no test harness, label its validation steps \`manual acceptance\`.]
|
|
48384
48387
|
|
|
48385
48388
|
#### Trade-offs
|
|
48386
48389
|
|
|
48387
|
-
[
|
|
48390
|
+
[State risks, compatibility limits, and deferred work.]
|
|
48388
48391
|
|
|
48389
48392
|
## Phases
|
|
48390
48393
|
|
|
48391
|
-
[
|
|
48394
|
+
[List ordered tasks with file or module targets. Keep design decisions in Design. Name application behavior for end-to-end tests and public module behavior for integration tests. Use separate Arrange, Act, and Assert steps. Follow the execution workflow permissions for commits and pushes.]
|
|
48392
48395
|
|
|
48393
48396
|
### Phase 1: [Outcome]
|
|
48394
48397
|
|
|
@@ -48397,9 +48400,9 @@ var spec_driven_plan_default = `# [Outcome to deliver]
|
|
|
48397
48400
|
- [ ] [Task C]
|
|
48398
48401
|
- [ ] [Task D]
|
|
48399
48402
|
- [ ] Validation
|
|
48400
|
-
- [ ] [
|
|
48401
|
-
- [ ] [
|
|
48402
|
-
- [ ] [
|
|
48403
|
+
- [ ] [Make sure that the observable application or module contract passes its test.]
|
|
48404
|
+
- [ ] [Run format, lint, and build tasks.]
|
|
48405
|
+
- [ ] [If execution authorizes commits and expects CI, commit changes and make sure that CI passes.]
|
|
48403
48406
|
|
|
48404
48407
|
### Phase 2: [Outcome]
|
|
48405
48408
|
|
|
@@ -48408,9 +48411,9 @@ var spec_driven_plan_default = `# [Outcome to deliver]
|
|
|
48408
48411
|
- [ ] [Task C]
|
|
48409
48412
|
- [ ] [Task D]
|
|
48410
48413
|
- [ ] Validation
|
|
48411
|
-
- [ ] [
|
|
48412
|
-
- [ ] [
|
|
48413
|
-
- [ ] [
|
|
48414
|
+
- [ ] [Make sure that the observable application or module contract passes its test.]
|
|
48415
|
+
- [ ] [Run format, lint, and build tasks.]
|
|
48416
|
+
- [ ] [If execution authorizes commits and expects CI, commit changes and make sure that CI passes.]
|
|
48414
48417
|
|
|
48415
48418
|
### Phase 3: [Outcome]
|
|
48416
48419
|
|
|
@@ -48419,46 +48422,48 @@ var spec_driven_plan_default = `# [Outcome to deliver]
|
|
|
48419
48422
|
- [ ] [Task C]
|
|
48420
48423
|
- [ ] [Task D]
|
|
48421
48424
|
- [ ] Validation
|
|
48422
|
-
- [ ] [
|
|
48423
|
-
- [ ] [
|
|
48424
|
-
- [ ] [
|
|
48425
|
+
- [ ] [Make sure that the observable application or module contract passes its test.]
|
|
48426
|
+
- [ ] [Run format, lint, and build tasks.]
|
|
48427
|
+
- [ ] [If execution authorizes commits and expects CI, commit changes and make sure that CI passes.]
|
|
48425
48428
|
|
|
48426
48429
|
## References
|
|
48427
48430
|
|
|
48428
|
-
- [Source or
|
|
48429
|
-
- [
|
|
48431
|
+
- [Source issue or architecture decision.]
|
|
48432
|
+
- [Supporting external specification or documentation.]
|
|
48433
|
+
- [Related repository path or prior plan.]
|
|
48430
48434
|
`;
|
|
48431
48435
|
var init_spec_driven_plan = () => {};
|
|
48432
48436
|
|
|
48433
48437
|
// templates/software-architecture-design.md
|
|
48434
|
-
var software_architecture_design_default = `# [System or feature]
|
|
48438
|
+
var software_architecture_design_default = `# [System or feature]: software architecture
|
|
48435
48439
|
|
|
48436
48440
|
## Overview
|
|
48437
48441
|
|
|
48438
|
-
[
|
|
48442
|
+
[State the purpose, system boundary, users, and explicit non-goals.]
|
|
48439
48443
|
|
|
48440
48444
|
## Requirement
|
|
48441
48445
|
|
|
48442
48446
|
### Functional
|
|
48443
48447
|
|
|
48444
|
-
[
|
|
48448
|
+
[List observable behavioral capabilities from a client, caller, or end-user perspective. Use plain bullets without \`FR\` prefixes. Put internal types, function names, configuration internals, file layouts, and code-style rules in Design and Implementation.]
|
|
48445
48449
|
|
|
48446
|
-
-
|
|
48447
|
-
-
|
|
48448
|
-
-
|
|
48450
|
+
- [Client or end-user capability and observable outcome.]
|
|
48451
|
+
- [Additional client or end-user capability and observable outcome.]
|
|
48452
|
+
- [Explicit behavioral boundary or rejection rule.]
|
|
48449
48453
|
|
|
48450
48454
|
### Non-Functional
|
|
48451
48455
|
|
|
48452
|
-
[
|
|
48456
|
+
[List performance, security, cost, isolation, and reliability characteristics from a client, caller, or end-user perspective. Use plain bullets without \`NFR\` prefixes. Put internal mechanisms in Design and Implementation.]
|
|
48453
48457
|
|
|
48454
|
-
-
|
|
48455
|
-
-
|
|
48458
|
+
- [Observable performance, reliability, or cost bound.]
|
|
48459
|
+
- [Observable security or isolation guarantee.]
|
|
48460
|
+
- [Additional external operational characteristic.]
|
|
48456
48461
|
|
|
48457
48462
|
## Design
|
|
48458
48463
|
|
|
48459
48464
|
### Components and Responsibilities
|
|
48460
48465
|
|
|
48461
|
-
[
|
|
48466
|
+
[Draw a system diagram and list each component with its responsibility and relationships. Use Mermaid diagrams unless \`AGENTS.md\` states another format.]
|
|
48462
48467
|
|
|
48463
48468
|
> @agent: add example mermaid diagram
|
|
48464
48469
|
|
|
@@ -48466,31 +48471,33 @@ var software_architecture_design_default = `# [System or feature] \u2014 softwar
|
|
|
48466
48471
|
|
|
48467
48472
|
\`\`\`
|
|
48468
48473
|
|
|
48469
|
-
- Component A
|
|
48470
|
-
-
|
|
48471
|
-
-
|
|
48474
|
+
- [Component A handles this responsibility.]
|
|
48475
|
+
- [Component A calls Component B for that responsibility.]
|
|
48476
|
+
- [Component C stores this state.]
|
|
48472
48477
|
|
|
48473
48478
|
### Data and Control Flow
|
|
48474
48479
|
|
|
48475
|
-
[
|
|
48480
|
+
[Trace the main request or event path and name where state lives. If a flowchart or sequence diagram clarifies the path, include it.]
|
|
48476
48481
|
|
|
48477
48482
|
### Interfaces and Contracts
|
|
48478
48483
|
|
|
48479
|
-
[
|
|
48484
|
+
[List database entities, input and output schemas, endpoints, core types, and public methods. If data models change, include an entity-relationship diagram.]
|
|
48480
48485
|
|
|
48481
48486
|
## Implementation
|
|
48482
48487
|
|
|
48483
48488
|
### Important topic 1
|
|
48484
48489
|
|
|
48485
|
-
[
|
|
48490
|
+
[List owned modules, dependency direction, and extension points.]
|
|
48486
48491
|
|
|
48487
48492
|
### Important topic 2
|
|
48488
48493
|
|
|
48489
|
-
[
|
|
48494
|
+
[List operational rules, configuration internals, or code-level invariants.]
|
|
48490
48495
|
|
|
48491
48496
|
## References
|
|
48492
48497
|
|
|
48493
48498
|
- [Relevant code, ADR, or external specification.]
|
|
48499
|
+
- [Related design document or issue.]
|
|
48500
|
+
- [Applicable external standard or API contract.]
|
|
48494
48501
|
`;
|
|
48495
48502
|
var init_software_architecture_design = () => {};
|
|
48496
48503
|
|
|
@@ -48562,59 +48569,69 @@ var init_architecture_decision_record = () => {};
|
|
|
48562
48569
|
// templates/product-requirements-document.md
|
|
48563
48570
|
var product_requirements_document_default = `# [User outcome or product change]
|
|
48564
48571
|
|
|
48565
|
-
> @agent: make this closer to the PRD under prd dir!
|
|
48566
|
-
|
|
48567
48572
|
- **Status:** draft
|
|
48568
48573
|
- **Owner:** [person or team]
|
|
48569
48574
|
- **Date:** [YYYY-MM-DD]
|
|
48570
48575
|
|
|
48571
48576
|
## Summary
|
|
48572
48577
|
|
|
48573
|
-
[
|
|
48578
|
+
[State what changes for users and why it matters.]
|
|
48574
48579
|
|
|
48575
48580
|
## Problem and Evidence
|
|
48576
48581
|
|
|
48577
|
-
[
|
|
48582
|
+
[Name who has the problem and state observed evidence or explicit assumptions.]
|
|
48578
48583
|
|
|
48579
48584
|
## Users and Use Cases
|
|
48580
48585
|
|
|
48581
|
-
- [
|
|
48586
|
+
- [Primary user]: [Job to be done and context.]
|
|
48587
|
+
- [Secondary user]: [Job to be done and context.]
|
|
48588
|
+
- [Operator or caller]: [Job to be done and context.]
|
|
48582
48589
|
|
|
48583
48590
|
## Goals
|
|
48584
48591
|
|
|
48585
|
-
- [
|
|
48592
|
+
- [Primary user outcome to achieve.]
|
|
48593
|
+
- [Secondary user outcome to achieve.]
|
|
48594
|
+
- [Operational or quality outcome to achieve.]
|
|
48586
48595
|
|
|
48587
48596
|
## Non-Goals
|
|
48588
48597
|
|
|
48589
|
-
- [Related need that this work
|
|
48598
|
+
- [Related need that this work excludes.]
|
|
48599
|
+
- [Out-of-scope workflow or integration.]
|
|
48600
|
+
- [Deferred capability for a later release.]
|
|
48590
48601
|
|
|
48591
48602
|
## Proposed Experience
|
|
48592
48603
|
|
|
48593
|
-
[Describe the user journey, inputs, outputs,
|
|
48604
|
+
[Describe the user journey, inputs, outputs, error messages, and recovery path.]
|
|
48594
48605
|
|
|
48595
48606
|
## Requirements
|
|
48596
48607
|
|
|
48597
|
-
|
|
48608
|
+
[Describe observable behavioral capabilities and performance, security, cost, isolation, and reliability characteristics from an end-user or client perspective. Do not use \`FR\` or \`NFR\` prefixes. Leave internal types, function names, configuration internals, file layouts, and code-style rules out of this section.]
|
|
48609
|
+
|
|
48610
|
+
### [Capability or quality characteristic]
|
|
48598
48611
|
|
|
48599
|
-
[
|
|
48612
|
+
[State required user-facing behavior, edge cases, and operational bounds.]
|
|
48600
48613
|
|
|
48601
|
-
|
|
48614
|
+
Acceptance: [State an observable way to make sure that the requirement works.]
|
|
48602
48615
|
|
|
48603
48616
|
## Success Measures
|
|
48604
48617
|
|
|
48605
|
-
[
|
|
48618
|
+
[State the signal, baseline or assumption, target, and measurement method.]
|
|
48606
48619
|
|
|
48607
48620
|
## Risks and Dependencies
|
|
48608
48621
|
|
|
48609
|
-
- [
|
|
48622
|
+
- [Technical or product risk]: [Mitigation or owner.]
|
|
48623
|
+
- [External dependency]: [Mitigation or owner.]
|
|
48624
|
+
- [Operational or rollout risk]: [Mitigation or owner.]
|
|
48610
48625
|
|
|
48611
48626
|
## Open Questions
|
|
48612
48627
|
|
|
48613
|
-
- [
|
|
48628
|
+
- [Product decision and owner.]
|
|
48629
|
+
- [Scope question and owner.]
|
|
48630
|
+
- [Rollout question and owner.]
|
|
48614
48631
|
|
|
48615
48632
|
## Rollout
|
|
48616
48633
|
|
|
48617
|
-
[
|
|
48634
|
+
[Describe the release plan, feedback loop, migration path, and rollback steps.]
|
|
48618
48635
|
`;
|
|
48619
48636
|
var init_product_requirements_document = () => {};
|
|
48620
48637
|
|
|
@@ -48663,9 +48680,9 @@ var code_review_default = `# Review: [change or pull request]
|
|
|
48663
48680
|
- **Revision:** [commit or diff]
|
|
48664
48681
|
- **Intent:** [stated objective and source]
|
|
48665
48682
|
- **Reviewer:** [actual model identity]
|
|
48666
|
-
- **Mode:** [normal/adversarial
|
|
48683
|
+
- **Mode:** [normal/adversarial]
|
|
48667
48684
|
|
|
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.]
|
|
48685
|
+
[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.]
|
|
48669
48686
|
|
|
48670
48687
|
## Intent Delivery
|
|
48671
48688
|
|
|
@@ -48685,11 +48702,11 @@ var code_review_default = `# Review: [change or pull request]
|
|
|
48685
48702
|
|
|
48686
48703
|
## Reliability/Testing
|
|
48687
48704
|
|
|
48688
|
-
[
|
|
48705
|
+
[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.]
|
|
48689
48706
|
|
|
48690
48707
|
## Documentation
|
|
48691
48708
|
|
|
48692
|
-
[Flag walls of text, complex language, and text that only restates the implementation. Require concise
|
|
48709
|
+
[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.]
|
|
48693
48710
|
|
|
48694
48711
|
## Performance
|
|
48695
48712
|
|
|
@@ -48728,7 +48745,6 @@ State each finding once here, with its issue, effect, and useful fix. Use short,
|
|
|
48728
48745
|
|
|
48729
48746
|
- **Checks run:** [command and result.]
|
|
48730
48747
|
- **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
48748
|
- **Rubric:** [path to the copied YAML rubric with completed criterion results. Disclose missing, pending, skipped, or stale results.]
|
|
48733
48749
|
`;
|
|
48734
48750
|
var init_code_review = () => {};
|
|
@@ -48744,8 +48760,6 @@ review:
|
|
|
48744
48760
|
changed_files: []
|
|
48745
48761
|
exclusions: []
|
|
48746
48762
|
reviewers: []
|
|
48747
|
-
model_inputs: []
|
|
48748
|
-
model_results: []
|
|
48749
48763
|
sections:
|
|
48750
48764
|
- title: Intent Delivery
|
|
48751
48765
|
criteria:
|
|
@@ -48765,12 +48779,12 @@ sections:
|
|
|
48765
48779
|
scope: file
|
|
48766
48780
|
default_severity: consider
|
|
48767
48781
|
issue: >-
|
|
48768
|
-
Function or
|
|
48782
|
+
Function or symbol names misrepresent behavior, hide side effects, or break written naming rules.
|
|
48769
48783
|
results: []
|
|
48770
48784
|
- id: readability.structure
|
|
48771
48785
|
scope: file
|
|
48772
48786
|
default_severity: consider
|
|
48773
|
-
issue: The changed flow is
|
|
48787
|
+
issue: The changed control flow is hard to follow.
|
|
48774
48788
|
results: []
|
|
48775
48789
|
- title: Semantic Organization
|
|
48776
48790
|
criteria:
|
|
@@ -48782,25 +48796,25 @@ sections:
|
|
|
48782
48796
|
- id: organization.architecture
|
|
48783
48797
|
scope: review
|
|
48784
48798
|
default_severity: consider
|
|
48785
|
-
issue: Files or classes mix responsibilities, obscure ownership, or
|
|
48799
|
+
issue: Files or classes mix responsibilities, obscure ownership, or break written architecture rules.
|
|
48786
48800
|
results: []
|
|
48787
48801
|
- id: organization.api-ergonomics
|
|
48788
48802
|
scope: applicable-file
|
|
48789
48803
|
applies_when: Added or modified public APIs, exported types, methods, or classes.
|
|
48790
48804
|
default_severity: consider
|
|
48791
|
-
issue: Public APIs expose types unrelated to the module role or
|
|
48805
|
+
issue: Public APIs expose types unrelated to the module role or remain hard to discover and use.
|
|
48792
48806
|
results: []
|
|
48793
48807
|
- id: organization.new-files
|
|
48794
48808
|
scope: applicable-file
|
|
48795
48809
|
applies_when: Added source files that introduce a module or submodule. A rename alone does not qualify.
|
|
48796
48810
|
default_severity: consider
|
|
48797
48811
|
issue: >-
|
|
48798
|
-
A new file lacks a
|
|
48812
|
+
A new file lacks a clear module boundary or contains functions that belong in an existing module.
|
|
48799
48813
|
results: []
|
|
48800
48814
|
- id: organization.file-structure
|
|
48801
48815
|
scope: file
|
|
48802
48816
|
default_severity: consider
|
|
48803
|
-
issue: A file breaks the
|
|
48817
|
+
issue: A file breaks the prescribed section order or declaration layout.
|
|
48804
48818
|
results: []
|
|
48805
48819
|
- title: Maintainability
|
|
48806
48820
|
criteria:
|
|
@@ -48808,93 +48822,101 @@ sections:
|
|
|
48808
48822
|
scope: review
|
|
48809
48823
|
default_severity: consider
|
|
48810
48824
|
issue: >-
|
|
48811
|
-
New fields, types, wrappers, helpers, dependencies, or layers lack a
|
|
48825
|
+
New fields, types, wrappers, helpers, dependencies, or layers lack a clear caller need and add complexity.
|
|
48812
48826
|
results: []
|
|
48813
48827
|
- id: maintainability.complexity
|
|
48814
48828
|
scope: applicable-file
|
|
48815
48829
|
applies_when: >-
|
|
48816
|
-
Files with added or changed executable functions. For new functions,
|
|
48830
|
+
Files with added or changed executable functions. For new functions, evaluate whether required behavior needs the introduced branches.
|
|
48817
48831
|
default_severity: consider
|
|
48818
|
-
issue: Cyclomatic complexity grows
|
|
48832
|
+
issue: Cyclomatic complexity grows beyond what the required behavior needs.
|
|
48819
48833
|
results: []
|
|
48820
48834
|
- id: maintainability.utilities
|
|
48821
48835
|
scope: review
|
|
48822
48836
|
default_severity: consider
|
|
48823
|
-
issue: Duplicated state
|
|
48837
|
+
issue: Duplicated state, repeated logic, or inline work makes a function hard to read or maintain.
|
|
48824
48838
|
results: []
|
|
48825
48839
|
- id: maintainability.packages
|
|
48826
48840
|
scope: review
|
|
48827
48841
|
default_severity: consider
|
|
48828
48842
|
issue: >-
|
|
48829
|
-
Custom code recreates functionality that an established
|
|
48843
|
+
Custom code recreates functionality that an established package already provides.
|
|
48830
48844
|
results: []
|
|
48831
48845
|
- title: Reliability/Testing
|
|
48832
48846
|
criteria:
|
|
48833
48847
|
- id: testing.correctness
|
|
48834
48848
|
scope: file
|
|
48835
48849
|
default_severity: blocking
|
|
48836
|
-
issue: The changed code produces
|
|
48850
|
+
issue: The changed code produces wrong behavior.
|
|
48837
48851
|
results: []
|
|
48838
48852
|
- id: testing.application
|
|
48839
48853
|
scope: review
|
|
48840
48854
|
default_severity: consider
|
|
48841
48855
|
issue: >-
|
|
48842
|
-
Required behavior lacks outside-in test evidence (e2e
|
|
48856
|
+
Required behavior lacks outside-in test evidence (e2e over integration over unit), or tests lack human-verifiable outputs such as snapshots, logs, or JSON payloads.
|
|
48843
48857
|
results: []
|
|
48844
48858
|
- id: testing.relevance
|
|
48845
48859
|
scope: applicable-file
|
|
48846
48860
|
applies_when: Added or modified test files.
|
|
48847
48861
|
default_severity: consider
|
|
48848
48862
|
issue: >-
|
|
48849
|
-
Verbose unit tests pad coverage without proving real contracts
|
|
48863
|
+
Verbose unit tests pad coverage without proving real contracts or exercise only external dependencies. Tests inspect static asset or template structure, test the test apparatus, or add same-changeset or alpha regression tests.
|
|
48850
48864
|
results: []
|
|
48851
48865
|
- id: testing.names
|
|
48852
48866
|
scope: applicable-file
|
|
48853
48867
|
applies_when: Added or modified test files.
|
|
48854
48868
|
default_severity: consider
|
|
48855
48869
|
issue: >-
|
|
48856
|
-
A test name
|
|
48870
|
+
A test name omits the tested functionality or its expected outcome.
|
|
48857
48871
|
results: []
|
|
48858
48872
|
- id: testing.arrange-act-assert
|
|
48859
48873
|
scope: applicable-file
|
|
48860
48874
|
applies_when: Added or modified test files.
|
|
48861
48875
|
default_severity: consider
|
|
48862
48876
|
issue: >-
|
|
48863
|
-
Test organization lacks clear BDD
|
|
48877
|
+
Test organization lacks clear BDD structure (given, when, then) or mixes setup, actions, and assertions.
|
|
48864
48878
|
results: []
|
|
48865
48879
|
- id: testing.fixtures
|
|
48866
48880
|
scope: applicable-file
|
|
48867
48881
|
applies_when: Added or modified tests, fixtures, test setup, or test utility files.
|
|
48868
48882
|
default_severity: consider
|
|
48869
48883
|
issue: >-
|
|
48870
|
-
Repeated setup, unsuitable fixtures, or
|
|
48884
|
+
Repeated setup, unsuitable fixtures, or duplicated helpers obscure tests.
|
|
48871
48885
|
results: []
|
|
48872
48886
|
- title: Documentation
|
|
48873
48887
|
criteria:
|
|
48874
48888
|
- id: documentation.conciseness
|
|
48875
48889
|
scope: applicable-file
|
|
48876
|
-
applies_when: Added or modified documentation
|
|
48890
|
+
applies_when: Added or modified documentation and documentation comments.
|
|
48877
48891
|
default_severity: consider
|
|
48878
|
-
issue: Long, dense, or complex
|
|
48892
|
+
issue: Long, dense, or complex prose makes documentation hard to read.
|
|
48879
48893
|
results: []
|
|
48880
48894
|
- id: documentation.redundancy
|
|
48881
48895
|
scope: applicable-file
|
|
48882
|
-
applies_when: Added or modified documentation
|
|
48896
|
+
applies_when: Added or modified documentation and documentation comments.
|
|
48883
48897
|
default_severity: consider
|
|
48884
|
-
issue: Documentation repeats
|
|
48898
|
+
issue: Documentation repeats code or existing prose without adding context.
|
|
48885
48899
|
results: []
|
|
48886
48900
|
- id: documentation.visuals
|
|
48887
48901
|
scope: applicable-file
|
|
48888
48902
|
applies_when: Added or modified documentation that explains structures, flows, or relationships.
|
|
48889
48903
|
default_severity: consider
|
|
48890
|
-
issue:
|
|
48904
|
+
issue: Long prose hides structure or flow that a diagram or tree shows clearly.
|
|
48905
|
+
results: []
|
|
48906
|
+
- id: documentation.requirements
|
|
48907
|
+
scope: applicable-file
|
|
48908
|
+
applies_when: >-
|
|
48909
|
+
Added or modified plans, architecture designs, PRDs, or planning intents with Requirement or Requirements sections.
|
|
48910
|
+
default_severity: consider
|
|
48911
|
+
issue: >-
|
|
48912
|
+
Requirement or Requirements sections use FR or NFR prefixes or state internal implementation specifications. Requirements omit observable behavior or performance, security, cost, isolation, and reliability characteristics from a client or end-user perspective.
|
|
48891
48913
|
results: []
|
|
48892
48914
|
- title: Performance
|
|
48893
48915
|
criteria:
|
|
48894
48916
|
- id: performance.regressions
|
|
48895
48917
|
scope: review
|
|
48896
48918
|
default_severity: consider
|
|
48897
|
-
issue: The change
|
|
48919
|
+
issue: The change introduces a material performance regression.
|
|
48898
48920
|
results: []
|
|
48899
48921
|
- title: Security
|
|
48900
48922
|
optional: true
|
|
@@ -48912,19 +48934,19 @@ var planning_intent_default = `# Intent: [short name]
|
|
|
48912
48934
|
|
|
48913
48935
|
## Objective
|
|
48914
48936
|
|
|
48915
|
-
[
|
|
48937
|
+
[State what you want to add or change for clients, callers, or end users.]
|
|
48916
48938
|
|
|
48917
48939
|
## Requirements/Instructions
|
|
48918
48940
|
|
|
48919
|
-
[
|
|
48941
|
+
[List observable behavioral capabilities from a client, caller, or end-user perspective, or write direct instructions to follow. Use plain statements without \`FR\` or \`NFR\` prefixes. Leave internal types, function names, configuration internals, file layouts, and code-style rules out of requirements.]
|
|
48920
48942
|
|
|
48921
48943
|
## Constraints
|
|
48922
48944
|
|
|
48923
|
-
[
|
|
48945
|
+
[State observable performance, security, cost, isolation, and reliability characteristics, key invariants, or explicit boundaries. Optional.]
|
|
48924
48946
|
|
|
48925
48947
|
## Open Questions
|
|
48926
48948
|
|
|
48927
|
-
[
|
|
48949
|
+
[List product or design decisions that need input before planning. Optional.]
|
|
48928
48950
|
`;
|
|
48929
48951
|
var init_planning_intent = () => {};
|
|
48930
48952
|
|
|
@@ -49247,6 +49269,46 @@ The \`base_commit\` is the full SHA of \`origin/main\` when this branch was crea
|
|
|
49247
49269
|
`;
|
|
49248
49270
|
var init_poc_readme = () => {};
|
|
49249
49271
|
|
|
49272
|
+
// templates/hook-definition.md
|
|
49273
|
+
var hook_definition_default = `# {{name}}
|
|
49274
|
+
|
|
49275
|
+
## Trigger
|
|
49276
|
+
|
|
49277
|
+
{{trigger}}
|
|
49278
|
+
|
|
49279
|
+
## Action
|
|
49280
|
+
|
|
49281
|
+
- Handler: \`{{handler}}\`
|
|
49282
|
+
- Requires: \`{{requires}}\`
|
|
49283
|
+
- Receives: \`{{receives}}\`
|
|
49284
|
+
|
|
49285
|
+
## Instructions
|
|
49286
|
+
|
|
49287
|
+
{{instructions}}
|
|
49288
|
+
`;
|
|
49289
|
+
var init_hook_definition = () => {};
|
|
49290
|
+
|
|
49291
|
+
// templates/task.md
|
|
49292
|
+
var task_default = `# [Task title]
|
|
49293
|
+
|
|
49294
|
+
## Objective
|
|
49295
|
+
|
|
49296
|
+
[One-line description of what needs to be done.]
|
|
49297
|
+
|
|
49298
|
+
## Context
|
|
49299
|
+
|
|
49300
|
+
[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.]
|
|
49301
|
+
|
|
49302
|
+
## Technical Approach
|
|
49303
|
+
|
|
49304
|
+
_To be completed by the person doing the work._
|
|
49305
|
+
|
|
49306
|
+
## References
|
|
49307
|
+
|
|
49308
|
+
- [Relevant links to wikis, architecture docs, tickets, external resources, CI logs, or incident portals.]
|
|
49309
|
+
`;
|
|
49310
|
+
var init_task = () => {};
|
|
49311
|
+
|
|
49250
49312
|
// templates/examples/plan-feature.md
|
|
49251
49313
|
var plan_feature_default = `# Invite teammates to a project
|
|
49252
49314
|
|
|
@@ -49321,18 +49383,31 @@ src/
|
|
|
49321
49383
|
|
|
49322
49384
|
#### Testing
|
|
49323
49385
|
|
|
49386
|
+
\`\`\`mermaid
|
|
49387
|
+
flowchart TD
|
|
49388
|
+
Invite["Owner creates invitation"] --> Saved["State: Pending invitation saved<br/>(even if email queue fails)"]
|
|
49389
|
+
Saved --> Accept["Recipient submits token"]
|
|
49390
|
+
Accept --> Eligible{"Intended recipient,<br/>unused & unexpired?"}
|
|
49391
|
+
Eligible -->|"no"| Reject["Reject; membership & token unchanged"]
|
|
49392
|
+
Eligible -->|"yes"| Tx["Consume token + add member"]
|
|
49393
|
+
Tx -->|"tx fails"| Rollback["Roll back membership & token"]
|
|
49394
|
+
Tx -->|"tx succeeds"| Member["Return active membership"]
|
|
49395
|
+
\`\`\`
|
|
49396
|
+
|
|
49324
49397
|
\`\`\`text
|
|
49325
49398
|
src/
|
|
49326
49399
|
\u251C\u2500\u2500 http/
|
|
49327
49400
|
\u2502 \u2514\u2500\u2500 [A] invitations.spec.ts (application behavior)
|
|
49328
|
-
\u2502 \u2514\u2500\u2500 [A]
|
|
49329
|
-
\u2502 \u251C\u2500\u2500 [A]
|
|
49330
|
-
\u2502 \u2514\u2500\u2500 [A]
|
|
49401
|
+
\u2502 \u2514\u2500\u2500 [A] given a pending owner invitation
|
|
49402
|
+
\u2502 \u251C\u2500\u2500 [A] when the intended recipient accepts, then membership appears in JSON response
|
|
49403
|
+
\u2502 \u2514\u2500\u2500 [A] when a wrong recipient or expired/used token is submitted, then it rejects without changing state
|
|
49331
49404
|
\u2514\u2500\u2500 invitations/
|
|
49332
49405
|
\u2514\u2500\u2500 [A] service.spec.ts (public module behavior)
|
|
49333
|
-
\
|
|
49334
|
-
|
|
49335
|
-
\u2514\u2500\u2500 [A]
|
|
49406
|
+
\u251C\u2500\u2500 [A] given an email queue failure, when creating an invitation, then the saved invitation stays pending for retry
|
|
49407
|
+
\u2514\u2500\u2500 [A] given a pending invitation (converged state)
|
|
49408
|
+
\u2514\u2500\u2500 [A] when the database transaction fails during acceptance
|
|
49409
|
+
\u251C\u2500\u2500 [A] then membership changes roll back
|
|
49410
|
+
\u2514\u2500\u2500 [A] then the invitation token remains unconsumed
|
|
49336
49411
|
\`\`\`
|
|
49337
49412
|
|
|
49338
49413
|
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.
|
|
@@ -49444,17 +49519,26 @@ src/
|
|
|
49444
49519
|
|
|
49445
49520
|
#### Testing
|
|
49446
49521
|
|
|
49522
|
+
\`\`\`mermaid
|
|
49523
|
+
flowchart TD
|
|
49524
|
+
Write["writeActivity(event)"] --> Dual["Dual write with stable ID"]
|
|
49525
|
+
Dual -->|"destination fails"| Retry["Retry failed store"] --> Parity["State: Both stores hold identical events"]
|
|
49526
|
+
Backfill["Interrupted backfill"] --> Resume["Resume batch"] --> Parity
|
|
49527
|
+
Parity --> Cutover["Switch read flag to new store"]
|
|
49528
|
+
Cutover --> ReadCutover["Page history across cutover"]
|
|
49529
|
+
Cutover --> Rollback["Write post-cutover events, then roll back flag"]
|
|
49530
|
+
\`\`\`
|
|
49531
|
+
|
|
49447
49532
|
\`\`\`text
|
|
49448
49533
|
src/
|
|
49449
49534
|
\u2514\u2500\u2500 activity/
|
|
49450
49535
|
\u251C\u2500\u2500 [M] history.spec.ts (application behavior)
|
|
49451
|
-
\u2502 \u2514\u2500\u2500 [A]
|
|
49452
|
-
\u2502 \u251C\u2500\u2500 [A]
|
|
49453
|
-
\u2502 \u2514\u2500\u2500 [A]
|
|
49536
|
+
\u2502 \u2514\u2500\u2500 [A] given dual-written stores at parity (converged state)
|
|
49537
|
+
\u2502 \u251C\u2500\u2500 [A] when paging history across reader cutover, then records and cursors match
|
|
49538
|
+
\u2502 \u2514\u2500\u2500 [A] when rolling back the reader after new writes, then no events are lost
|
|
49454
49539
|
\u2514\u2500\u2500 [A] migration.spec.ts (public module behavior)
|
|
49455
|
-
\
|
|
49456
|
-
|
|
49457
|
-
\u2514\u2500\u2500 [A] given an interrupted backfill, when resumed, then IDs and order match without duplicates
|
|
49540
|
+
\u251C\u2500\u2500 [A] given a failed destination write, when retried, then one logical event exists in each store
|
|
49541
|
+
\u2514\u2500\u2500 [A] given an interrupted backfill batch, when resumed, then IDs and order match without duplicates
|
|
49458
49542
|
\`\`\`
|
|
49459
49543
|
|
|
49460
49544
|
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.
|
|
@@ -49500,25 +49584,26 @@ Dual writes increase latency and allow partial failure. Record discrepancies and
|
|
|
49500
49584
|
var init_plan_migration = () => {};
|
|
49501
49585
|
|
|
49502
49586
|
// templates/examples/design-service.md
|
|
49503
|
-
var design_service_default = `# Notification service
|
|
49587
|
+
var design_service_default = `# Notification service: software architecture
|
|
49504
49588
|
|
|
49505
49589
|
## Overview
|
|
49506
49590
|
|
|
49507
|
-
The service
|
|
49591
|
+
The notification service sends email notifications for account events. Callers submit events without waiting for email delivery. The service does not choose notification recipients.
|
|
49508
49592
|
|
|
49509
49593
|
## Requirement
|
|
49510
49594
|
|
|
49511
49595
|
### Functional
|
|
49512
49596
|
|
|
49513
|
-
-
|
|
49514
|
-
-
|
|
49515
|
-
-
|
|
49597
|
+
- Callers submit account events with an event ID, event type, recipient address, and timestamp, and the service rejects malformed events.
|
|
49598
|
+
- Recipients receive an email for each valid account event, and callers can inspect the delivery outcome for each event.
|
|
49599
|
+
- The service retries temporary email failures automatically and reports permanent rejections.
|
|
49516
49600
|
|
|
49517
49601
|
### Non-Functional
|
|
49518
49602
|
|
|
49519
|
-
-
|
|
49520
|
-
-
|
|
49521
|
-
-
|
|
49603
|
+
- Submitting the same event ID more than once sends at most one email to the recipient.
|
|
49604
|
+
- Callers submit events without holding email provider credentials, and event payloads never expose secrets.
|
|
49605
|
+
- Event bursts do not add latency to caller account requests, and operators receive an alert when pending deliveries grow.
|
|
49606
|
+
- Duplicate and permanently rejected events do not trigger paid provider retries.
|
|
49522
49607
|
|
|
49523
49608
|
## Design
|
|
49524
49609
|
|
|
@@ -49533,32 +49618,32 @@ flowchart LR
|
|
|
49533
49618
|
Consumer --> Store[(Attempt store)]
|
|
49534
49619
|
\`\`\`
|
|
49535
49620
|
|
|
49536
|
-
- The account service publishes events and
|
|
49537
|
-
- The durable queue
|
|
49538
|
-
- The consumer
|
|
49539
|
-
- The attempt store records event IDs, delivery outcomes, and retry
|
|
49621
|
+
- The account service publishes events and depends only on the event contract.
|
|
49622
|
+
- The durable queue decouples email delivery from account requests and retries temporary failures.
|
|
49623
|
+
- The consumer parses and deduplicates events before the sender submits mail to the provider.
|
|
49624
|
+
- The attempt store records event IDs, delivery outcomes, and retry counts.
|
|
49540
49625
|
|
|
49541
49626
|
### Data and Control Flow
|
|
49542
49627
|
|
|
49543
|
-
An account event enters the queue. The consumer
|
|
49628
|
+
An account event enters the queue. The consumer parses the payload and queries the attempt store for the event ID before the sender calls the provider. The consumer records each attempt. The queue retries temporary failures, and the consumer reports permanent rejections. Synchronous delivery avoids the queue, but slow provider responses then delay account requests.
|
|
49544
49629
|
|
|
49545
49630
|
### Interfaces and Contracts
|
|
49546
49631
|
|
|
49547
|
-
\`AccountEvent\` contains \`id\`, \`type\`, \`recipient\`, and \`timestamp\`. \`handle(event)\`
|
|
49632
|
+
\`AccountEvent\` contains \`id\`, \`type\`, \`recipient\`, and \`timestamp\`. \`handle(event)\` processes the event, \`send(message)\` calls the provider, and \`record(attempt)\` saves the result. The event ID acts as the deduplication key. Provider credentials never enter the event payload.
|
|
49548
49633
|
|
|
49549
49634
|
## Implementation
|
|
49550
49635
|
|
|
49551
49636
|
### Consumer and storage
|
|
49552
49637
|
|
|
49553
|
-
The notification service owns
|
|
49638
|
+
The notification service owns the consumer and attempt store. The account service imports only the event contract. Save the deduplication key with the delivery outcome so queue redelivery stays safe. Integration tests cover duplicate events and provider timeouts.
|
|
49554
49639
|
|
|
49555
49640
|
### Delivery operations
|
|
49556
49641
|
|
|
49557
|
-
Keep provider credentials
|
|
49642
|
+
Keep provider credentials inside the notification service configuration. Alert operators when the queue grows or when provider calls fail repeatedly. If credentials leak, disable sending and drain pending work. Load tests cover event bursts so account request latency stays flat.
|
|
49558
49643
|
|
|
49559
49644
|
## References
|
|
49560
49645
|
|
|
49561
|
-
- EX-34
|
|
49646
|
+
- EX-34: example notification requirement.
|
|
49562
49647
|
`;
|
|
49563
49648
|
var init_design_service = () => {};
|
|
49564
49649
|
|
|
@@ -49747,7 +49832,6 @@ Address the two requests. No unrelated cleanup is needed.
|
|
|
49747
49832
|
- **Checks run:** None. This is a fictional example.
|
|
49748
49833
|
- **Not verified:** Execution and real repository guidance.
|
|
49749
49834
|
- **Rubric:** A real review links its filled rubric here.
|
|
49750
|
-
- **Council:** Not selected.
|
|
49751
49835
|
`;
|
|
49752
49836
|
var init_review_change = () => {};
|
|
49753
49837
|
|
|
@@ -49919,6 +50003,8 @@ var init_source = __esm(() => {
|
|
|
49919
50003
|
init_exploration_research();
|
|
49920
50004
|
init_exploration_proposal();
|
|
49921
50005
|
init_poc_readme();
|
|
50006
|
+
init_hook_definition();
|
|
50007
|
+
init_task();
|
|
49922
50008
|
init_plan_feature();
|
|
49923
50009
|
init_plan_migration();
|
|
49924
50010
|
init_design_service();
|
|
@@ -49946,6 +50032,8 @@ var init_source = __esm(() => {
|
|
|
49946
50032
|
"exploration-research.md": exploration_research_default,
|
|
49947
50033
|
"exploration-proposal.md": exploration_proposal_default,
|
|
49948
50034
|
"poc-readme.md": poc_readme_default,
|
|
50035
|
+
"hook-definition.md": hook_definition_default,
|
|
50036
|
+
"task.md": task_default,
|
|
49949
50037
|
"examples/plan-feature.md": plan_feature_default,
|
|
49950
50038
|
"examples/plan-migration.md": plan_migration_default,
|
|
49951
50039
|
"examples/design-service.md": design_service_default,
|
|
@@ -49977,7 +50065,9 @@ var init_source = __esm(() => {
|
|
|
49977
50065
|
{ name: "exploration-summary", description: "Source-grounded technical exploration summary" },
|
|
49978
50066
|
{ name: "exploration-research", description: "Technical exploration research notes" },
|
|
49979
50067
|
{ name: "exploration-proposal", description: "Optional technical exploration approach" },
|
|
49980
|
-
{ name: "poc-readme", description: "Disposable proof-of-concept branch README" }
|
|
50068
|
+
{ name: "poc-readme", description: "Disposable proof-of-concept branch README" },
|
|
50069
|
+
{ name: "hook-definition", description: "Reusable global Agent Skill hook definition" },
|
|
50070
|
+
{ name: "task", description: "Terse task or bug ticket with objective, context, and references" }
|
|
49981
50071
|
];
|
|
49982
50072
|
embeddedSource = {
|
|
49983
50073
|
catalog,
|
|
@@ -52536,7 +52626,7 @@ function createProgram(write = console.log, version = "0.1.0", options = {}) {
|
|
|
52536
52626
|
|
|
52537
52627
|
// src/index.ts
|
|
52538
52628
|
init_errors3();
|
|
52539
|
-
var version2 = "0.
|
|
52629
|
+
var version2 = "0.13.1";
|
|
52540
52630
|
try {
|
|
52541
52631
|
await createProgram(console.log, version2).parseAsync(process.argv);
|
|
52542
52632
|
} catch (error) {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@difflab/difflab-cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.13.1",
|
|
4
4
|
"private": false,
|
|
5
5
|
"description": "A minimal Bun CLI starter built with Commander",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -47,7 +47,7 @@
|
|
|
47
47
|
},
|
|
48
48
|
"devDependencies": {
|
|
49
49
|
"@types/bun": "1.4.2",
|
|
50
|
-
"difflab-db": "workspace:*",
|
|
50
|
+
"difflab-db-legacy": "workspace:*",
|
|
51
51
|
"prettier": "3.9.8",
|
|
52
52
|
"typescript": "7.0.2",
|
|
53
53
|
"utils": "workspace:*"
|