Skip to content

Commit 55d7782

Browse files
Goosterhofclaude
andcommitted
docs(claude-md): consolidate cascade-tax + string-ts + Doctrine #8 doctrine
Four edits to CLAUDE.md, sourced from Adjutant M2 doctrine inquiry (2026-05-07): - Add `## Versioning Discipline (Pre-1.0)` — encodes the mechanical per-bump checklist (widen ranges, patch-bump siblings, regenerate lock, verify no nested registry copies). Notes that `workspace:*` is not an option on npm (rejected as EUNSUPPORTEDPROTOCOL). - Add `### Internal Dependency Coordination` sub-section under `## Conventions` — captures the string-ts version-sync discipline between fs-helpers and fs-translation. Reframes the "duplicate bundle" claim against verified npm dedupe behavior. - Add `## Doctrine #8 — HTTP Timeout Surface (fs-http)` — surfaces fs-http as the war-room reference implementation of the library-author extension to Architectural Principle #8 (verbatim quote from war-room CLAUDE.md). Documents the 5-axis surface. - Fix TypeScript version line: `5.9+` → `^6.0` (matches root package.json#devDependencies.typescript). No code or test changes; markdown only. Order: orders/fs-packages/claude-md-doctrine-consolidation-engineer-deployment.md Adjutant field report: reports/fs-packages/field/2026-05-07-adjutant-doctrine-inquiry-cascade-tax-string-ts.md Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent ba1a16e commit 55d7782

1 file changed

Lines changed: 37 additions & 1 deletion

File tree

CLAUDE.md

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Shared frontend service packages monorepo under the `@script-development` npm sc
44

55
## Stack
66

7-
- **Language:** TypeScript 5.9+ (strict mode, `verbatimModuleSyntax`)
7+
- **Language:** TypeScript ^6.0 (strict mode, `verbatimModuleSyntax`)
88
- **Build:** tsdown (Rolldown/oxc) — dual ESM + CJS output
99
- **Test:** vitest 4 (100% coverage threshold) + Stryker (90% mutation threshold)
1010
- **Lint:** oxlint (explicit config at `.oxlintrc.json`)
@@ -13,6 +13,22 @@ Shared frontend service packages monorepo under the `@script-development` npm sc
1313
- **Publish:** OIDC Trusted Publishing to public npm registry (no stored tokens)
1414
- **CI:** 8-gate pipeline: audit → format → lint → build → typecheck → lint:pkg → coverage → mutation
1515

16+
## Doctrine #8 — HTTP Timeout Surface (fs-http)
17+
18+
`fs-http` is the war-room reference implementation of Doctrine #8 (Architectural Principle #8, library-author extension — see war-room `CLAUDE.md` `## Architectural Principles` §8, 2026-04-22):
19+
20+
> **Library-author extension (2026-04-22)** — Shared HTTP factory packages (e.g., `@script-development/fs-http`) must expose a compliant timeout surface: a default, a required option, or a documented contract plus consumer-level enforcement. Inheriting framework defaults at the library layer silently propagates the violation to every consumer territory.
21+
22+
`fs-http` exposes a 5-axis timeout surface:
23+
24+
- **Default:** `30000` ms applied if no override is provided.
25+
- **Service-wide option:** `createHttpService(baseURL, { timeout: number })`.
26+
- **Per-request override:** standard axios `timeout` config on individual calls.
27+
- **Opt-out:** `timeout: 0` disables the timeout (use sparingly).
28+
- **Constant export:** `DEFAULT_TIMEOUT_MS` is barrel-exported for consumers that need to reference the default explicitly.
29+
30+
Consumer territories must apply per-call timeouts at instantiation OR rely on the 30000 ms default. See `docs/packages/http.md#timeout` for usage.
31+
1632
## Packages (10)
1733

1834
| Package | Vue | Description |
@@ -37,6 +53,26 @@ Shared frontend service packages monorepo under the `@script-development` npm sc
3753
- **Test environment:** Browser-dependent tests use `// @vitest-environment happy-dom` file-level comments.
3854
- **Identical build config:** All packages share the same `tsdown.config.ts` structure.
3955

56+
### Internal Dependency Coordination
57+
58+
Two packages share an internal direct-dep on `string-ts`: `fs-helpers` (`deepCamelKeys`, `deepSnakeKeys`, `DeepSnakeKeys` type) and `fs-translation` (`replaceAll`). Symbols are disjoint, npm dedupes the dep in consumer `node_modules` when ranges align, and tsdown externalizes string-ts in both bundles — consumers using both packages do **not** ship duplicate copies.
59+
60+
**Discipline:** when bumping `string-ts` in either package, bump it in the other in the same PR. Range drift across the two consumers (e.g. one on `^2.x`, the other on `^3.x`) breaks consumer dedupe.
61+
62+
## Versioning Discipline (Pre-1.0)
63+
64+
While packages remain pre-1.0, npm caret semantics treat every minor bump as breaking (`^0.1.0` matches only `0.1.x`). Each `fs-http` minor bump cascades into peer-range widenings on `fs-loading` and `fs-adapter-store`. The cascade is mechanical, not avoidable on npm.
65+
66+
Per-bump checklist:
67+
68+
1. Grep all `packages/*/package.json` for the bumped package's name.
69+
2. For every match in `dependencies` / `devDependencies` / `peerDependencies`, widen the range (e.g. `^0.1.0``^0.1.0 || ^0.2.0`).
70+
3. Patch-bump the affected sibling packages — the peer-range widening is observable in published metadata and deserves its own version.
71+
4. Regenerate `package-lock.json` and verify every `node_modules/@script-development/*` resolves to the workspace (`"resolved": "packages/*"`, `"link": true`). No nested registry copies anywhere in the lock.
72+
5. CI passing `npm ci` is necessary but not sufficient — inspect the lock for nested copies after every cross-minor bump.
73+
74+
This tax disappears once packages reach 1.0. The `workspace:*` protocol is **not** an option on npm (npm 11+ rejects it as `EUNSUPPORTEDPROTOCOL`); it is a pnpm/yarn feature.
75+
4076
## Commands
4177

4278
| Command | Purpose |

0 commit comments

Comments
 (0)