From bba833e4eaefff283c67e351a6fa61b0a3d93cb5 Mon Sep 17 00:00:00 2001 From: logohere <69400476+logohere@users.noreply.github.com> Date: Sun, 1 Nov 2026 01:24:50 -0500 Subject: [PATCH 1/5] chore: align the unreleased candidate to 1.0.0 --- AGENTS.md | 2 +- CHANGELOG.md | 2 +- CONTRIBUTING.md | 2 +- bun.lock | 2 +- docs/spec-kit-extension.md | 2 +- docs/v1-release-plan.md | 2 +- docs/v1-security-audit.md | 2 +- extension.yml | 2 +- packages/dotdog/CHANGELOG.md | 2 +- packages/dotdog/package.json | 2 +- 10 files changed, 10 insertions(+), 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4ed9743..fcabecc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,5 +45,5 @@ dotdog status → read-only graph freshness (not correctness) 1. Use conventional commits (feat:, fix:, docs:, chore:) 2. Never commit dist/ -3. Every code change touching `packages/dotdog/src/` or `package.json` must bump version +3. Keep the first unreleased 1.0 candidate at `1.0.0`; bump versions per release, not per development commit 4. Dogfood: test against `npx dotdog@latest validate` before shipping diff --git a/CHANGELOG.md b/CHANGELOG.md index 9cac131..7ab42aa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## 1.0.1 — Unreleased +## 1.0.0 — Unreleased - Validate nested workspace JSON before exposing typed data; preserve existing validation JSON and reject malformed/incomplete groups without crashes. - Retain graph coverage/limitations and MCP node provenance, distinguish bounded searches, and keep token-budget errors bounded without silently dropping scope. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b613134..01121f1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -76,7 +76,7 @@ dotdog follows **MAJOR.MINOR.PATCH** (semver). | New feature | MINOR | 0.5.1 → 0.6.0 | | Breaking change | MAJOR | 0.6.0 → 1.0.0 | -**Every code change gets a version bump.** No accumulating changes across releases. +Version numbers identify releases, not individual commits. Keep the first unreleased 1.0 candidate at `1.0.0` while its fixes and features are developed. Choose the next version relative to the last published release when preparing a new release; keep package, extension and lockfile metadata aligned. Local `npm pack` checks create test archives and do not publish to the registry. ### Docs diff --git a/bun.lock b/bun.lock index 9773500..f240b22 100644 --- a/bun.lock +++ b/bun.lock @@ -10,7 +10,7 @@ }, "packages/dotdog": { "name": "dotdog", - "version": "1.0.1", + "version": "1.0.0", "bin": { "dotdog": "dist/cli.js", "spec": "dist/cli.js", diff --git a/docs/spec-kit-extension.md b/docs/spec-kit-extension.md index 8fb21f9..3b717dc 100644 --- a/docs/spec-kit-extension.md +++ b/docs/spec-kit-extension.md @@ -9,7 +9,7 @@ Dotdog imports GitHub Spec Kit feature artifacts into local, queryable knowledge ## 1.0 development -The next extension version is 1.0.1 and is not published yet. Its release archive will be `https://github.com/specdog/dotdog/releases/download/v1.0.1/dotdog-spec-kit-extension-v1.0.1.zip`. The installation below refers to the existing published 0.9.0 extension until the next release is created. +The next extension version is 1.0.0 and is not published yet. Its release archive will be `https://github.com/specdog/dotdog/releases/download/v1.0.0/dotdog-spec-kit-extension-v1.0.0.zip`. The installation below refers to the existing published 0.9.0 extension until the next release is created. ## Requirements diff --git a/docs/v1-release-plan.md b/docs/v1-release-plan.md index a0a971c..45e72eb 100644 --- a/docs/v1-release-plan.md +++ b/docs/v1-release-plan.md @@ -119,7 +119,7 @@ The separate TypeScript 7.0.2 CLI probe checked valid → invalid → repaired c ## 6. Release integrity and approval -After required gates pass, approve the final commit and version. The current development version is 1.0.1; align metadata to the approved version without silently downgrading it. Follow the repository's source/package version-bump rule. Do not commit build output. +The first release target is `1.0.0`. Keep that version across unshipped development commits and align package, extension, lockfile and changelog metadata. Local package checks do not publish to npm. After required gates pass, approve the final commit and artifact. Do not commit build output. Pack the final candidate once, retain commit/version/file manifest/digests, test those exact bytes and publish only that archive. Changed candidate bytes invalidate the previous artifact approval. Resolve approved prerelease feedback before stable publication; prerelease publication also requires approval. diff --git a/docs/v1-security-audit.md b/docs/v1-security-audit.md index f0267d9..968061a 100644 --- a/docs/v1-security-audit.md +++ b/docs/v1-security-audit.md @@ -50,7 +50,7 @@ See [migration](v1-migration.md), [peer research](graph-peer-research.md) and [e ## Scoped gap repair -The unreleased `1.0.1` candidate repairs malformed nested workspace input before registry construction and removes the resolver's unchecked JSON-to-config assertion. Success-only typed data passes real `strict`/`exactOptionalPropertyTypes` compiler checks; invalid-result data access is rejected with TS2339. No runtime schema dependency was added. +The workspace-boundary repair at `22b0b7e` repairs malformed nested workspace input before registry construction and removes the resolver's unchecked JSON-to-config assertion. Success-only typed data passes real `strict`/`exactOptionalPropertyTypes` compiler checks; invalid-result data access is rejected with TS2339. No runtime schema dependency was added. `path --dag` previously bypassed repository and file-size checks. It now uses the shared safe reader; a regression confirms that an external graph cannot be returned. Traversal results retain supplied coverage and node provenance, disclose search boundaries, and fail explicitly when scope metadata cannot fit the requested token budget. diff --git a/extension.yml b/extension.yml index 3dac250..e2de35f 100644 --- a/extension.yml +++ b/extension.yml @@ -3,7 +3,7 @@ "extension": { "id": "dotdog", "name": "Dotdog", - "version": "1.0.1", + "version": "1.0.0", "description": "Import GitHub Spec Kit artifacts into local knowledge graphs for validation, analysis, search, and MCP queries.", "author": "specdog", "repository": "https://github.com/specdog/dotdog", diff --git a/packages/dotdog/CHANGELOG.md b/packages/dotdog/CHANGELOG.md index 2888159..69b3631 100644 --- a/packages/dotdog/CHANGELOG.md +++ b/packages/dotdog/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## 1.0.1 — Unreleased +## 1.0.0 — Unreleased - Validate nested workspace JSON before exposing typed data; preserve existing validation JSON and reject malformed/incomplete groups without crashes. - Retain graph coverage/limitations and MCP node provenance, distinguish bounded searches, and keep token-budget errors bounded without silently dropping scope. diff --git a/packages/dotdog/package.json b/packages/dotdog/package.json index 8ac9a6d..69223f8 100644 --- a/packages/dotdog/package.json +++ b/packages/dotdog/package.json @@ -1,6 +1,6 @@ { "name": "dotdog", - "version": "1.0.1", + "version": "1.0.0", "description": "CLI tool for structured software specifications. Validate .dog files, compile .dag graphs, query via MCP.", "type": "module", "main": "dist/cli.js", From add88ff73ca9566a3df8861b28bd011495c45f2d Mon Sep 17 00:00:00 2001 From: logohere <69400476+logohere@users.noreply.github.com> Date: Sun, 1 Nov 2026 01:58:00 -0500 Subject: [PATCH 2/5] ci: verify pinned Spec Kit minimum and current releases --- .../verify-spec-kit-extension-release.yml | 21 ++++++++++++++++--- docs/graph-peer-research.md | 6 ++++++ docs/spec-kit-extension.md | 2 ++ 3 files changed, 26 insertions(+), 3 deletions(-) diff --git a/.github/workflows/verify-spec-kit-extension-release.yml b/.github/workflows/verify-spec-kit-extension-release.yml index 6449660..ba3ec64 100644 --- a/.github/workflows/verify-spec-kit-extension-release.yml +++ b/.github/workflows/verify-spec-kit-extension-release.yml @@ -18,18 +18,28 @@ jobs: verify-release: runs-on: ubuntu-latest timeout-minutes: 15 + strategy: + fail-fast: false + matrix: + include: + - version: '0.12.0' + revision: '96892954ad335a6803c163ed1830a35a019138af' + - version: '1.2.5' + revision: '4572a67fe0e72a6837e2d7bb0fda875bc41482e5' steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 with: persist-credentials: false - - name: Install current GitHub Spec Kit + - name: Install pinned GitHub Spec Kit shell: bash + env: + SPEC_KIT_REVISION: ${{ matrix.revision }} run: | set -euo pipefail python3 -m venv "$RUNNER_TEMP/spec-kit-venv" "$RUNNER_TEMP/spec-kit-venv/bin/python" -m pip install --disable-pip-version-check \ - 'git+https://github.com/github/spec-kit.git@main' + "git+https://github.com/github/spec-kit.git@$SPEC_KIT_REVISION" - name: Prepare and verify extension bundle id: bundle @@ -70,23 +80,28 @@ jobs: - name: Install release through Spec Kit env: VERIFY_VERSION: ${{ steps.bundle.outputs.version }} + SPEC_KIT_VERSION: ${{ matrix.version }} shell: bash run: | set -euo pipefail "$RUNNER_TEMP/spec-kit-venv/bin/python" - "$RUNNER_TEMP" "$VERIFY_VERSION" <<'PY' + import os import sys + from importlib.metadata import version as installed_version from pathlib import Path from specify_cli.extensions import ExtensionManager temp = Path(sys.argv[1]) version = sys.argv[2] + speckit_version = installed_version("specify-cli") + assert speckit_version == os.environ["SPEC_KIT_VERSION"], speckit_version archive = temp / f"dotdog-spec-kit-extension-v{version}.zip" project = temp / "spec-kit-project" project.mkdir() manifest = ExtensionManager(project).install_from_zip( archive, - speckit_version="0.12.17", + speckit_version=speckit_version, ) assert manifest.id == "dotdog" assert manifest.version == version diff --git a/docs/graph-peer-research.md b/docs/graph-peer-research.md index b5ce0c9..e83f93e 100644 --- a/docs/graph-peer-research.md +++ b/docs/graph-peer-research.md @@ -5,6 +5,12 @@ title: Graph tooling research — October 2026 # Graph tooling research — October 2026 +## Spec tooling update — 2026-11-01 + +GitHub [Spec Kit 1.2.5](https://github.com/github/spec-kit/releases/tag/v1.2.5), released October 28, includes workflow discovery through MCP and extension validation fixes. [OpenSpec 1.16.0](https://github.com/Fission-AI/OpenSpec/releases/tag/v1.16.0), released October 30, adds scenario-step diagnostics and makes invalid configuration fail validation. These are upstream releases, not Dotdog versions, and activity does not establish better development outcomes. + +For Dotdog 1.0, retain the existing Spec Kit extension and test its declared minimum/current release using pinned sources and actual installed versions. Keep malformed configuration, unmet acceptance criteria, source freshness and requirement-to-check links explicit. Scenario syntax and compiler acceptance are separate from behavioral testing; no workflow engine, mandatory OpenSpec/Kiro installation or new backend is needed. Broader compatibility or additional spec formats require their own tested scope. + Selected high-star graph/context peers, discovered through GitHub search and checked with the GitHub repository API on 2026-10-29. This is not an exhaustive ranking, a quality score or a reproduced performance comparison. Features below are documented by their maintainers unless source inspection is stated. | Project | Stars at snapshot | Relevant documented pattern | Dotdog decision | diff --git a/docs/spec-kit-extension.md b/docs/spec-kit-extension.md index 3b717dc..e982892 100644 --- a/docs/spec-kit-extension.md +++ b/docs/spec-kit-extension.md @@ -17,6 +17,8 @@ The next extension version is 1.0.0 and is not published yet. Its release archiv - Dotdog 0.9.0 or newer - A Spec Kit project containing `.specify/` and `specs/` +Extension compatibility CI uses pinned Spec Kit 0.12.0 and 1.2.5 sources and the installed package's actual version. It verifies archive installation and command files, not agent-host execution. Current-head CI results determine compatibility; a declared minimum alone is not evidence that it passed. + Install Dotdog: ```bash From 85eb2250c62f43f5ed1e428a57000c05b8e84e76 Mon Sep 17 00:00:00 2001 From: logohere <69400476+logohere@users.noreply.github.com> Date: Sun, 1 Nov 2026 03:24:07 -0500 Subject: [PATCH 3/5] fix: close graph, hook and release-integrity audit gaps --- .github/workflows/test.yml | 5 ++- docs/retrieval-benchmarks.md | 4 +-- packages/dotdog/__tests__/context.test.ts | 14 ++++++++ .../dotdog/__tests__/release-audit.test.ts | 32 +++++++++++++++++++ packages/dotdog/skills/dotdog/SKILL.md | 2 +- packages/dotdog/src/automation.ts | 3 ++ packages/dotdog/src/graph/commands.ts | 2 +- packages/dotdog/src/graph/model.ts | 2 +- packages/dotdog/src/serve.ts | 2 +- scripts/check-release.mjs | 3 +- scripts/publish-release.mjs | 2 ++ 11 files changed, 63 insertions(+), 8 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 40ae2fb..107e66e 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -25,6 +25,9 @@ jobs: node: '24' - os: windows-latest node: '24' + - os: ubuntu-latest + node: '24' + bun: '1.4.4' runs-on: ${{ matrix.os }} timeout-minutes: 15 steps: @@ -37,7 +40,7 @@ jobs: node-version: ${{ matrix.node }} - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 with: - bun-version: '1.3.14' + bun-version: ${{ matrix.bun || '1.3.14' }} - run: bun install --frozen-lockfile - run: bun run lint - run: node scripts/check-speckit-extension.mjs diff --git a/docs/retrieval-benchmarks.md b/docs/retrieval-benchmarks.md index 09b1c3d..8a2e84f 100644 --- a/docs/retrieval-benchmarks.md +++ b/docs/retrieval-benchmarks.md @@ -54,9 +54,9 @@ This is a genuine research direction, not lossless compression or a speed guaran For Dotdog, retain exact ID maps and graph relationships. Evaluate VSA only as an optional candidate-retrieval experiment, followed by exact evidence lookup. A model cannot consume arbitrary superposed vectors as readable facts without an appropriate decoder. Smaller vector storage must not be advertised as fewer prompt tokens. -## Remaining required evaluation +## Research-only evaluation -The follow-up [token-budgeted context evaluation](context-budgets.md) now measures frozen structural tasks on two real repositories. It compares existing context with lexical task ranking and an actual tokenizer budget. Neither pass completes the 1.0 performance gate: no standalone lexical/semantic-vector/VSA backend comparison or model answer evaluation has run yet. +The follow-up [token-budgeted context evaluation](context-budgets.md) measures frozen structural tasks on two real repositories. It compares existing context with lexical task ranking and an actual tokenizer budget. Standalone semantic-vector/VSA comparisons and model answer evaluations have not run; they are prerequisites for future research claims, not 1.0 release gates or required product features. The scoped 1.0 performance review covers existing CLI, refresh and graph/type workflows. 1. Label real repository tasks with required evidence, difficult distractors and no-answer cases. Keep held-out tasks separate from tuning; include code, authored intent and reverse-engineering evidence without treating inferred links as facts. 2. Compare lexical retrieval, semantic-vector candidates, graph expansion and VSA under identical corpus/snapshot, top-k and context budgets. Record recall@k, ranking, evidence coverage, unsupported selections and answer abstention before claiming savings. diff --git a/packages/dotdog/__tests__/context.test.ts b/packages/dotdog/__tests__/context.test.ts index 8dc8b20..0a7a2dd 100644 --- a/packages/dotdog/__tests__/context.test.ts +++ b/packages/dotdog/__tests__/context.test.ts @@ -57,6 +57,20 @@ describe('token-budgeted context', () => { await expect(budgetContext(graphNeighborhood(graph, 'root'), 1024, 'x'.repeat(4097))).rejects.toThrow('task'); }); + test('ambiguous neighborhoods and MCP context expose exact candidate IDs and omitted candidates', async () => { + const root = mkdtempSync(join(tmpdir(), 'dotdog-ambiguous-')); + try { + const raw = { project: 'ambiguous', nodes: Array.from({ length: 130 }, (_, i) => ({ id: `entity:${i}`, label: 'Duplicate' })), edges: [] }; + const result = graphNeighborhood(normalizeGraph(raw), 'Duplicate'); + expect(result.truncated).toBe(true); + expect(result.candidates).toHaveLength(100); + writeFileSync(join(root, 'ambiguous.dag'), JSON.stringify(raw)); + const response = await createMcpHandler(root)({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'context', arguments: { project: 'ambiguous', q: 'Duplicate', limit: 3 } } }); + expect(response.result.structuredContent.candidates).toEqual(['entity:0', 'entity:1', 'entity:2']); + expect(response.result.structuredContent.truncated).toBe(true); + } finally { rmSync(root, { recursive: true, force: true }); } + }); + test('bounds ambiguous candidate errors and treats special-token spellings as ordinary data', async () => { const result = await budgetContext({ ok: false, error: 'ambiguous_endpoint', candidates: Array.from({ length: 100 }, (_, i) => `<|im_start|>${i}${'🐕'.repeat(40)}`) }, 160); expect(tokens(result)).toBeLessThanOrEqual(160); diff --git a/packages/dotdog/__tests__/release-audit.test.ts b/packages/dotdog/__tests__/release-audit.test.ts index 3eb10c0..87712aa 100644 --- a/packages/dotdog/__tests__/release-audit.test.ts +++ b/packages/dotdog/__tests__/release-audit.test.ts @@ -13,6 +13,7 @@ import { graphStatus } from '../src/automation'; import { scenarioCheck, referenceCheck } from '../src/spec/checks'; import { createMcpHandler } from '../src/serve'; import { MAX_GRAPH_BYTES } from '../src/graph/io'; +import { minimalChildEnv } from '../src/workspace/environment'; import { setupTempProject } from './helpers'; const dirs: string[] = []; @@ -21,6 +22,37 @@ const cli = join(import.meta.dir, '../src/cli.ts'); const run = (cwd: string, ...args: string[]) => spawnSync(process.execPath, [cli, ...args], { cwd, encoding: 'utf8' }); afterEach(() => { for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true }); }); +test('publishing refuses a different source commit and tampered verified archive', () => { + const root = fixture(), artifact = 'dotdog-1.0.0.tgz', bytes = Buffer.from('release-fixture'); + mkdirSync(join(root, 'packages/dotdog'), { recursive: true }); + writeFileSync(join(root, 'packages/dotdog/package.json'), JSON.stringify({ version: '1.0.0' })); + writeFileSync(join(root, artifact), bytes); + const manifest = { verified: true, version: '1.0.0', commit: 'a'.repeat(40), artifact, sha256: createHash('sha256').update(bytes).digest('hex'), integrity: 'sha512-' + createHash('sha512').update(bytes).digest('base64') }; + const metadata = join(root, 'release.json'), npm = join(root, 'npm-cli.js'); + writeFileSync(npm, 'require("node:fs").writeFileSync("publish-args.json", JSON.stringify(process.argv.slice(2)));'); + const publish = (commit: string) => spawnSync('node', [join(import.meta.dir, '../../../scripts/publish-release.mjs'), metadata], { cwd: root, encoding: 'utf8', env: minimalChildEnv({ GITHUB_ACTIONS: 'true', GITHUB_REF_NAME: 'v1.0.0', GITHUB_SHA: commit, npm_execpath: npm }) }); + writeFileSync(metadata, JSON.stringify(manifest)); + expect(publish('b'.repeat(40)).status).not.toBe(0); + expect(() => readFileSync(join(root, 'publish-args.json'))).toThrow(); + writeFileSync(join(root, artifact), 'tampered'); + expect(publish(manifest.commit).status).not.toBe(0); + expect(() => readFileSync(join(root, 'publish-args.json'))).toThrow(); + writeFileSync(join(root, artifact), bytes); + expect(publish(manifest.commit).status).toBe(0); + expect(JSON.parse(readFileSync(join(root, 'publish-args.json'), 'utf8'))).toEqual(['publish', join(root, artifact), '--access', 'public', '--provenance']); +}); + +test('Claude hook install rejects malformed settings without rewriting them or recording ownership', () => { + for (const settings of [[], null, { hooks: [] }, { hooks: { PostToolUse: {} } }]) { + const root = fixture(); mkdirSync(join(root, '.claude')); + const bytes = JSON.stringify(settings), file = join(root, '.claude/settings.json'); + writeFileSync(file, bytes); + expect(run(root, 'hooks', 'install', '--agent', 'claude').status).not.toBe(0); + expect(readFileSync(file, 'utf8')).toBe(bytes); + expect(() => readFileSync(join(root, '.doghouse/hooks/claude.json'))).toThrow(); + } +}); + test('read-only status detects changed inputs and missing outputs without repairing them', () => { const root = fixture(); writeFileSync(join(root, 'a.ts'), 'export const a = 1;'); diff --git a/packages/dotdog/skills/dotdog/SKILL.md b/packages/dotdog/skills/dotdog/SKILL.md index 6783ee8..92b9292 100644 --- a/packages/dotdog/skills/dotdog/SKILL.md +++ b/packages/dotdog/skills/dotdog/SKILL.md @@ -12,7 +12,7 @@ Use the repository's installed Dotdog version. Never install packages, hooks, or 4. Preserve semantic/overlay inputs. Refresh generated artifacts after relevant edits. Use existing project tests to verify behavior; `dotdog check --json` validates graph integrity, not application correctness. 5. Report evidence, limits, unresolved references and truncation. An impact graph is a dependency neighborhood, not proof of every runtime effect. A small graph or successful check does not prove complete repository coverage. -For REA/Ghidra work, use the already configured analysis workflow. Dotdog only imports supplied graph evidence with `dotdog graph import --format rea-callgraph --project `. Supply `--artifact-sha256` when the analyzed binary identity is known. Do not launch, register, install, or reconfigure an analysis provider through Dotdog. +For REA/Ghidra work, use the already configured analysis workflow. Dotdog only imports supplied graph evidence with `dotdog graph import --format rea-callgraph --project --rea-direction forward`. Use `backward` for caller exports, matching the producer request; the export body omits direction. Supply `--artifact-sha256` when the analyzed binary identity is known. Do not launch, register, install, or reconfigure an analysis provider through Dotdog. Automation is optional: `dotdog hooks install --agent git` checks the staged snapshot; `--agent claude` refreshes after edits. Only install when the user requests it. `dotdog hooks status` shows registration and `dotdog hooks remove --agent ` removes Dotdog's contribution. CI should run a pinned Dotdog version and `dotdog check` independently of editor hooks. diff --git a/packages/dotdog/src/automation.ts b/packages/dotdog/src/automation.ts index 57d4b18..3ea0aa4 100644 --- a/packages/dotdog/src/automation.ts +++ b/packages/dotdog/src/automation.ts @@ -166,6 +166,9 @@ export function registerAutomation(program: Command) { safeOutputPath(target, root); mkdirSync(dirname(target), { recursive: true }); const settings = existsSync(target) ? JSON.parse(readFileSync(target, 'utf8')) : {}; + if (!settings || typeof settings !== 'object' || Array.isArray(settings) + || settings.hooks !== undefined && (!settings.hooks || typeof settings.hooks !== 'object' || Array.isArray(settings.hooks)) + || settings.hooks?.PostToolUse !== undefined && !Array.isArray(settings.hooks.PostToolUse)) throw new Error('Invalid Claude settings; preserve the file and repair its object/hook shape before installing'); const command = 'dotdog refresh --if-stale'; const hook = { matcher: 'Write|Edit|MultiEdit', hooks: [{ type: 'command', command, timeout: 30 }] }; settings.hooks ||= {}; diff --git a/packages/dotdog/src/graph/commands.ts b/packages/dotdog/src/graph/commands.ts index 95d9b79..aaa1426 100644 --- a/packages/dotdog/src/graph/commands.ts +++ b/packages/dotdog/src/graph/commands.ts @@ -84,7 +84,7 @@ export function registerGraphCommands(program: Command) { const data = normalizeGraph(JSON.parse(readGraphText(resolveUserPath(opts.dag)))); const result = auditGraph(data, process.cwd(), { profile: opts.profile, maxAgeDays: Number(opts.maxAgeDays) }); if (!result.ok) process.exitCode = 1; - console.log(opts.json ? JSON.stringify(result, null, 2) : `${result.ok ? 'Evidence checks passed' : 'Evidence gaps found'}: ${result.validEvidence}/${result.evidence} current artifacts\n${result.findings.map(item => `${item.node}: ${item.code}: ${item.message}`).join('\n')}\nAdvisory only; not safety certification or actuation permission.`); + console.log(opts.json ? JSON.stringify(result, null, 2) : `${result.ok ? 'Evidence checks passed' : 'Evidence gaps found'}: ${result.validEvidence}/${result.evidence} current artifacts\n${result.findings.map(item => `${item.node}: ${item.code}: ${item.message}`).join('\n')}\n${result.limitations.join('\n')}`); }); graph.command('import ') .option('--format ', 'dotdog or rea-callgraph', 'dotdog') diff --git a/packages/dotdog/src/graph/model.ts b/packages/dotdog/src/graph/model.ts index 2cfdb40..c59285e 100644 --- a/packages/dotdog/src/graph/model.ts +++ b/packages/dotdog/src/graph/model.ts @@ -188,7 +188,7 @@ export function graphNeighborhood(graph: NormalizedGraph, query: string, options const byIdMatch = index.byId.get(query); const exact = byIdMatch ? [byIdMatch] : index.byFoldedName.get(query.toLowerCase()) || []; const scope = graphScope(graph); - if (exact.length !== 1) return { ...scope, ok: false as const, error: exact.length ? 'ambiguous_endpoint' : 'endpoint_not_found', candidates: exact.slice(0, 100).map(node => node.id), nodes: [], edges: [], truncated: false }; + if (exact.length !== 1) return { ...scope, ok: false as const, error: exact.length ? 'ambiguous_endpoint' : 'endpoint_not_found', candidates: exact.slice(0, 100).map(node => node.id), nodes: [], edges: [], truncated: exact.length > 100 }; const direction = options.direction || 'any', depth = options.depth ?? 2, limit = options.limit ?? 100; if (!Number.isInteger(depth) || depth < 0 || depth > 12 || !Number.isInteger(limit) || limit < 1 || limit > 1000) throw new Error('depth must be 0–12 and limit 1–1000'); const visited = new Set([exact[0].id]), edges = new Map(); diff --git a/packages/dotdog/src/serve.ts b/packages/dotdog/src/serve.ts index ec23ccb..d8c83d3 100644 --- a/packages/dotdog/src/serve.ts +++ b/packages/dotdog/src/serve.ts @@ -181,7 +181,7 @@ export function createMcpHandler(dir: string) { const exact = idMatch ? [idMatch] : index.byLabel.get(args.q) || []; const matches = exact.length ? exact : graph.nodes.filter(node => `${node.label} ${node.description || ''}`.toLowerCase().includes(args.q.toLowerCase())); const context = matches.length !== 1 - ? { ...graphScope(graph), ok: false, error: matches.length ? 'ambiguous_endpoint' : 'endpoint_not_found', candidates: matches.slice(0, args.limit || 100).map(node => node.label) } + ? { ...graphScope(graph), ok: false, error: matches.length ? 'ambiguous_endpoint' : 'endpoint_not_found', candidates: matches.slice(0, args.limit || 100).map(node => node.id), truncated: matches.length > (args.limit || 100) } : graphNeighborhood(graph, matches[0].id, { depth: args.depth, limit: args.limit }, index); return success(id, args.maxTokens === undefined ? context : await budgetContext(context, args.maxTokens, args.task)); } diff --git a/scripts/check-release.mjs b/scripts/check-release.mjs index 576f2e3..dbfdb16 100644 --- a/scripts/check-release.mjs +++ b/scripts/check-release.mjs @@ -80,7 +80,8 @@ try { assert.throws(() => run('graph', 'audit', '--dag', '.doghouse/imported/bench-fixture.dag', '--profile', 'embodied', '--json'), error => error.status === 1); const bun = execFileSync('bun', [cli, '--version'], { cwd: project, encoding: 'utf8' }).trim(); assert.equal(bun, version); - const manifest = { version, artifact: basename(artifact), sha256, integrity, size: bytes.length, node: process.versions.node, verified: true }; + const commit = execFileSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf8' }).trim(); + const manifest = { version, commit, artifact: basename(artifact), sha256, integrity, size: bytes.length, node: process.versions.node, ...(packed ? { files: packed.files } : {}), verified: true }; if (values.output) writeFileSync(join(output, 'release.json'), JSON.stringify(manifest, null, 2) + '\n'); console.log(JSON.stringify(manifest)); } finally { diff --git a/scripts/publish-release.mjs b/scripts/publish-release.mjs index 2dc3dec..6ca5704 100644 --- a/scripts/publish-release.mjs +++ b/scripts/publish-release.mjs @@ -13,6 +13,8 @@ assert.equal(manifest.artifact, basename(manifest.artifact)); assert.equal(manifest.artifact, `dotdog-${version}.tgz`); assert.ok([`v${version}`, `v${version}-npm`].includes(process.env.GITHUB_REF_NAME)); assert.equal(process.env.GITHUB_ACTIONS, 'true'); +assert.match(manifest.commit, /^[a-f0-9]{40}$/); +assert.equal(manifest.commit, process.env.GITHUB_SHA); const artifact = join(dirname(file), manifest.artifact), bytes = readFileSync(artifact); assert.equal(createHash('sha256').update(bytes).digest('hex'), manifest.sha256); assert.equal('sha512-' + createHash('sha512').update(bytes).digest('base64'), manifest.integrity); From ff1204b8a0f4adad2fb7901b83e8b27499f66db8 Mon Sep 17 00:00:00 2001 From: logohere <69400476+logohere@users.noreply.github.com> Date: Sun, 1 Nov 2026 03:36:10 -0500 Subject: [PATCH 4/5] docs: record scoped 1.0 audit and same-source performance evidence --- CHANGELOG.md | 3 + README.md | 4 +- .../retrieval/release-build-review.json | 284 ++++++++++++++++++ docs/agent.json | 3 +- docs/index.md | 4 +- docs/llms.txt | 2 +- docs/path-performance.md | 21 ++ docs/v1-migration.md | 2 + docs/v1-release-plan.md | 13 +- docs/v1-security-audit.md | 102 +++---- llms.txt | 2 +- packages/dotdog/CHANGELOG.md | 3 + packages/dotdog/README.md | 4 +- packages/dotdog/src/infra/verify.ts | 2 +- packages/dotdog/src/types/type-worker.ts | 2 +- 15 files changed, 367 insertions(+), 84 deletions(-) create mode 100644 benchmarks/retrieval/release-build-review.json diff --git a/CHANGELOG.md b/CHANGELOG.md index ff55342..f2bd02e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,9 @@ ## 1.0.0 — Unreleased +- Reject malformed Claude hook settings without overwriting them; disclose omitted ambiguity candidates with exact IDs in graph/MCP context errors. +- Bind verified release archives to source commits and retain package file manifests; share parser chunks and defer tokenizer loading without adding runtime dependencies. + - Add opt-in selected TypeScript 7.0.2 contract inspection with original project diagnostics, bounded declared-type references and retained compiler/config/source evidence; no declaration emit or automatic compiler installation. - Store BFS parent links instead of copying full path histories for each queued node; skip adjacency construction for zero-hop paths. diff --git a/README.md b/README.md index 7db4821..e98c7cf 100644 --- a/README.md +++ b/README.md @@ -139,7 +139,7 @@ dotdog graph audit --dag .doghouse/imported/system.dag --profile evidence --json `status` is read-only and exits nonzero when graphs are stale or absent. `scenario-check` checks one named Scenario/Flow for lexical compiled-entity references. `reference-check` checks explicit Verify file/property mappings without writing human plans. None proves application correctness. `staleness`, `simulate` and `verify` are deprecated compatibility names; `verify --init` is retired. -`graph audit` checks recorded artifact hashes, timestamps and results. Its optional embodied profile reports missing asset/requirement/sensor/actuator/hazard links. It does not operate hardware, run simulations or certify safety. See the embodied evidence guide for the exact graph conventions. +`graph audit` checks recorded artifact hashes, timestamps and results. This establishes artifact identity and reported traceability, not requirement satisfaction or runtime correctness. ## Limits and migration @@ -152,7 +152,7 @@ dotdog graph audit --dag .doghouse/imported/system.dag --profile evidence --json See [retrieval measurements and superposition assessment](docs/retrieval-benchmarks.md) for the controlled benchmark, exact tokenizer baseline and remaining evaluation limits. -See [security audit](docs/v1-security-audit.md), [peer research](docs/graph-peer-research.md), [embodied evidence](docs/embodied-systems.md), [migration](docs/v1-migration.md), [audit and research](docs/npm-0.9-audit.md), and [integrations](docs/integrations.md). The independent Rust port remains in [PR #330](https://github.com/specdog/dotdog/pull/330); npm/Bun delivery is not being replaced by it. +See [security review](docs/v1-security-audit.md), [migration](docs/v1-migration.md), and [integrations](docs/integrations.md). ## Development diff --git a/benchmarks/retrieval/release-build-review.json b/benchmarks/retrieval/release-build-review.json new file mode 100644 index 0000000..3e72820 --- /dev/null +++ b/benchmarks/retrieval/release-build-review.json @@ -0,0 +1,284 @@ +{ + "schema": 1, + "date": "2026-11-01", + "scope": "Same-source Node CLI build comparison: non-split versus shared chunks. Synthetic 200-file static-import fixture; not end-to-end agent productivity.", + "runtime": { + "node": "26.8.1", + "platform": "darwin", + "arch": "arm64", + "compiler": "7.0.2" + }, + "samples": 20, + "warmup": 3, + "order": "Alternating variant order within each case; sequential commands; warm OS filesystem cache", + "revision": "85eb2250c62f43f5ed1e428a57000c05b8e84e76", + "sourceDiffSha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", + "entrySha256": { + "nonSplit": "28b79cc9d300cc7acb0c64a89b88cc23a9a5d42de8135125a8ed183e7c9c5775", + "shared": "594ba3c09ad3f49c51016c0de544ae6f895a728fcc5eb66f32d2afab83020d14" + }, + "cases": { + "version": { + "nonSplit": { + "latencyMs": { + "p50": 104.74591600000008, + "p95": 106.47962499999994 + }, + "osMaxRssBytes": { + "p50": 94928896, + "max": 96976896 + }, + "serializedBytes": { + "min": 6, + "max": 6 + } + }, + "shared": { + "latencyMs": { + "p50": 61.12287500000002, + "p95": 63.918874999999844 + }, + "osMaxRssBytes": { + "p50": 53067776, + "max": 53673984 + }, + "serializedBytes": { + "min": 6, + "max": 6 + } + } + }, + "coldRefresh": { + "nonSplit": { + "latencyMs": { + "p50": 218.91483399999925, + "p95": 220.8099170000005 + }, + "osMaxRssBytes": { + "p50": 116211712, + "max": 118554624 + }, + "serializedBytes": { + "min": 8204, + "max": 8204 + } + }, + "shared": { + "latencyMs": { + "p50": 164.21670900000026, + "p95": 168.9195409999993 + }, + "osMaxRssBytes": { + "p50": 76447744, + "max": 77692928 + }, + "serializedBytes": { + "min": 8204, + "max": 8204 + } + } + }, + "warmRefresh": { + "nonSplit": { + "latencyMs": { + "p50": 127.22591599999942, + "p95": 130.30716700000085 + }, + "osMaxRssBytes": { + "p50": 100499456, + "max": 103022592 + }, + "serializedBytes": { + "min": 302, + "max": 302 + } + }, + "shared": { + "latencyMs": { + "p50": 83.33454200000051, + "p95": 84.77737499999967 + }, + "osMaxRssBytes": { + "p50": 59932672, + "max": 60293120 + }, + "serializedBytes": { + "min": 302, + "max": 302 + } + } + }, + "singleFileEdit": { + "nonSplit": { + "latencyMs": { + "p50": 200.19737499999974, + "p95": 204.8996249999982 + }, + "osMaxRssBytes": { + "p50": 116801536, + "max": 119685120 + }, + "serializedBytes": { + "min": 410, + "max": 410 + } + }, + "shared": { + "latencyMs": { + "p50": 154.08949999999822, + "p95": 158.18429200000173 + }, + "osMaxRssBytes": { + "p50": 77234176, + "max": 77856768 + }, + "serializedBytes": { + "min": 410, + "max": 410 + } + } + }, + "context": { + "nonSplit": { + "latencyMs": { + "p50": 110.5837079999983, + "p95": 111.57487499999843 + }, + "osMaxRssBytes": { + "p50": 99188736, + "max": 102105088 + }, + "serializedBytes": { + "min": 3799, + "max": 3799 + } + }, + "shared": { + "latencyMs": { + "p50": 66.91812500000015, + "p95": 69.30083400000149 + }, + "osMaxRssBytes": { + "p50": 57016320, + "max": 57540608 + }, + "serializedBytes": { + "min": 3799, + "max": 3799 + } + } + }, + "impact": { + "nonSplit": { + "latencyMs": { + "p50": 110.69387500000084, + "p95": 112.47912500000166 + }, + "osMaxRssBytes": { + "p50": 99713024, + "max": 101236736 + }, + "serializedBytes": { + "min": 2515, + "max": 2515 + } + }, + "shared": { + "latencyMs": { + "p50": 67.39879099999962, + "p95": 69.7532080000019 + }, + "osMaxRssBytes": { + "p50": 57098240, + "max": 57507840 + }, + "serializedBytes": { + "min": 2515, + "max": 2515 + } + } + }, + "path": { + "nonSplit": { + "latencyMs": { + "p50": 111.19162499999948, + "p95": 113.89958299999853 + }, + "osMaxRssBytes": { + "p50": 98074624, + "max": 99827712 + }, + "serializedBytes": { + "min": 4455, + "max": 4455 + } + }, + "shared": { + "latencyMs": { + "p50": 67.16058399999747, + "p95": 69.28587499999412 + }, + "osMaxRssBytes": { + "p50": 57442304, + "max": 57704448 + }, + "serializedBytes": { + "min": 4455, + "max": 4455 + } + } + }, + "types": { + "nonSplit": { + "latencyMs": { + "p50": 419.88270800000464, + "p95": 466.0246659999975 + }, + "osMaxRssBytes": { + "p50": 98189312, + "max": 101629952 + }, + "serializedBytes": { + "min": 4025, + "max": 4025 + } + }, + "shared": { + "latencyMs": { + "p50": 373.093458000003, + "p95": 413.75616699999955 + }, + "osMaxRssBytes": { + "p50": 98533376, + "max": 103809024 + }, + "serializedBytes": { + "min": 4025, + "max": 4025 + } + } + } + }, + "equivalentPayloadSha256": { + "context": "a32689bcd99dbf2e25f556023b0e0d23f829db0c97ab6109156a6c171165bd7d", + "impact": "a9769f94ac7c742362345ba516190d5e0a74e0d50eebc6234b48bc3c2ade832c", + "path": "99f10afab107a0b6b23f184f07cfe78a747af98a9e195e204a5cc95c265401f4", + "types": "fb2f44a9b8e13791a1a4312b91325f49ae8c47214f691000116a0e62ab8908be" + }, + "limitations": [ + "Cold refresh removes generated artifacts, not the OS page cache.", + "Wall time includes the time wrapper and process creation.", + "Darwin time -l reports OS maximum resident set size, not aggregate simultaneous process-tree memory or a memory guarantee.", + "Refresh assertions check successful regeneration and change detection; exact result hashes apply only to the listed read-only queries/type contracts.", + "CLI results do not establish user-task success, billing savings or universal performance improvements." + ], + "fixture": { + "sourceFiles": 200, + "shape": "Static import chain m0.ts through m199.ts; separate single-source selected-type project; generated artifacts removed for cold refresh only" + }, + "bundler": { + "name": "bun", + "version": "1.3.14", + "difference": "--splitting only; same source and minification" + } +} diff --git a/docs/agent.json b/docs/agent.json index b3697b4..6570207 100644 --- a/docs/agent.json +++ b/docs/agent.json @@ -22,6 +22,7 @@ "Repository-scoped Codex and Claude skills", "Opt-in removable hooks and staged-index checks", "Local stdio MCP with bounded context and impact queries", - "Read-only import of saved REA NativeCallGraph evidence" + "Read-only import of saved REA NativeCallGraph evidence", + "Optional selected TypeScript 7.0.2 contracts and compiler diagnostics" ] } diff --git a/docs/index.md b/docs/index.md index e6a2a25..3153885 100644 --- a/docs/index.md +++ b/docs/index.md @@ -144,7 +144,7 @@ dotdog graph audit --dag .doghouse/imported/system.dag --profile evidence --json `status` is read-only and exits nonzero when graphs are stale or absent. `scenario-check` checks one named Scenario/Flow for lexical compiled-entity references. `reference-check` checks explicit Verify file/property mappings without writing human plans. None proves application correctness. `staleness`, `simulate` and `verify` are deprecated compatibility names; `verify --init` is retired. -`graph audit` checks recorded artifact hashes, timestamps and results. Its optional embodied profile reports missing asset/requirement/sensor/actuator/hazard links. It does not operate hardware, run simulations or certify safety. See the embodied evidence guide for the exact graph conventions. +`graph audit` checks recorded artifact hashes, timestamps and results. This establishes artifact identity and reported traceability, not requirement satisfaction or runtime correctness. ## Limits and migration @@ -157,7 +157,7 @@ dotdog graph audit --dag .doghouse/imported/system.dag --profile evidence --json See [retrieval measurements and superposition assessment](retrieval-benchmarks.md) for the controlled benchmark, exact tokenizer baseline and remaining evaluation limits. -See [security audit](v1-security-audit.md), [peer research](graph-peer-research.md), [embodied evidence](embodied-systems.md), [migration]({{ '/v1-migration.html' | relative_url }}), [audit and research]({{ '/npm-0.9-audit.html' | relative_url }}), and [integrations]({{ '/integrations.html' | relative_url }}). The independent Rust port remains in PR #330; npm/Bun delivery is not being replaced by it. +See [security review](v1-security-audit.md), [migration]({{ '/v1-migration.html' | relative_url }}), and [integrations]({{ '/integrations.html' | relative_url }}). ## Development diff --git a/docs/llms.txt b/docs/llms.txt index 70005cf..4586ac8 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -13,4 +13,4 @@ Run `dotdog refresh --if-stale`, query the relevant project, and verify cited so - [Security audit](https://specdog.github.io/dotdog/v1-security-audit): Reproduced repairs, dependency updates and unverified boundaries. - [Peer research](https://specdog.github.io/dotdog/graph-peer-research): Dated high-star graph/context comparison. -- [Embodied evidence](https://specdog.github.io/dotdog/embodied-systems): Advisory artifact and relationship checks, not device control. +- [Type contracts](https://specdog.github.io/dotdog/type-contracts): Optional selected TypeScript 7.0.2 contracts, diagnostics and bounded graph references. diff --git a/docs/path-performance.md b/docs/path-performance.md index 38508ba..1d99921 100644 --- a/docs/path-performance.md +++ b/docs/path-performance.md @@ -30,6 +30,27 @@ The corresponding local archives were 1,313,355 and 1,219,546 bytes, both includ ## Reproduce +### Completed CLI build review + +A same-source comparison at `85eb225` covers a synthetic 200-file static-import chain plus a selected-type fixture. Both builds use Bun 1.3.14 with identical entry points/minification; only `--splitting` differs. Node 26.8.1 commands run sequentially in alternating variant order, with three warmups and twenty measured samples per variant. [Sanitized measurements, entry hashes and equivalent-result hashes](../benchmarks/retrieval/release-build-review.json) retain the complete percentiles, output sizes and OS maximum-RSS observations. + +| Whole CLI case | Non-split p50 / p95 (ms) | Shared chunks p50 / p95 (ms) | +| --- | ---: | ---: | +| `--version` | 104.75 / 106.48 | 61.12 / 63.92 | +| Refresh without generated artifacts | 218.91 / 220.81 | 164.22 / 168.92 | +| Unchanged `refresh --if-stale` | 127.23 / 130.31 | 83.33 / 84.78 | +| Refresh after one source edit | 200.20 / 204.90 | 154.09 / 158.18 | +| Context | 110.58 / 111.57 | 66.92 / 69.30 | +| Impact | 110.69 / 112.48 | 67.40 / 69.75 | +| Four-hop path | 111.19 / 113.90 | 67.16 / 69.29 | +| Selected type inspection | 419.88 / 466.02 | 373.09 / 413.76 | + +Query outputs and selected type contracts/input identity match between variants. Refresh assertions require successful regeneration and correct change detection; they are not full-payload equivalence checks. Output byte sizes are unchanged. Darwin `time -l` maximum-RSS medians fall from about 95–117 MB to 53–77 MB on the non-type cases; type inspection remains about 98 MB. This is OS-reported maximum resident memory, not aggregate simultaneous process-tree memory or a memory guarantee. Timing includes process creation and the measurement wrapper; the OS filesystem cache is warm even for artifact-free refresh. + +To reproduce, build the same revision twice into separate output directories, omitting `--splitting` for the baseline. Supply the matching package metadata alongside each build. Generate files `src/m0.ts` through `src/m199.ts`, each exporting `value` and statically importing the next file except the last. Repeat `node dist/cli.js` version/refresh/context/impact/path commands under `/usr/bin/time -l`; select `file:src/m100.ts` and use outgoing `m100.ts` → `m104.ts` for the four-hop case. For the type case, use an explicit strict/no-emit ES2022/Bundler project with `Ready` and `commit(value: Ready): Ready`, and the same project-installed TypeScript 7.0.2. Alternate build order, assert results before comparing times, and keep raw machine-specific logs private. These measurements establish no universal or end-to-end agent speedup. + +### Path-search harness + From a built development checkout with its frozen dependencies installed, use a new temporary directory. These are maintainer benchmarks, not product prerequisites. ```sh diff --git a/docs/v1-migration.md b/docs/v1-migration.md index 80095d2..f8bdcd7 100644 --- a/docs/v1-migration.md +++ b/docs/v1-migration.md @@ -54,6 +54,8 @@ Path/context/impact/traverse results retain supplied graph coverage and limitati Workspace manifests now validate nested shape before registry construction. Optional properties must be omitted or have their declared type; explicit `null`/`undefined` is not omission. Invalid manifests report validation errors instead of `TypeError`. The internal parser exposes typed `data` only on success; the existing validation JSON shape is unchanged. +Ambiguous MCP context candidates now contain exact node IDs rather than repeated display labels. Context/impact/traverse report `truncated: true` when candidate IDs are omitted. Claude hook installation refuses malformed settings/hook collections before changing settings or registering ownership; repair the existing file rather than replacing unrelated configuration. + ## Interpretation limits Repository extraction covers inventory plus JS/TS top-level declarations and static relative imports/re-exports. Alias resolution, dynamic calls, whole-program behavior and non-JS/TS symbol extraction remain unverified. Git ignore rules are honored when a Git root is present. Scan/read errors fail rather than justify deleting an unseen suffix. diff --git a/docs/v1-release-plan.md b/docs/v1-release-plan.md index e79f883..99e5774 100644 --- a/docs/v1-release-plan.md +++ b/docs/v1-release-plan.md @@ -101,23 +101,24 @@ The focused [path-search comparison](path-performance.md) measures parent-link B ## Implementation status -The core implementation at `22b0b7e` passed 116 local tests and the [Linux Node 22/24, macOS Node 24 and Windows Node 24 matrix](https://github.com/specdog/dotdog/actions/runs/41268166006). Its fixes include checked workspace data, traversal provenance/coverage, bounded search and context errors, repository-safe path reads and explicit REA direction. Real forward/backward Ghidra fixture checks passed without executing or changing the target. See [audit](v1-security-audit.md), [migration](v1-migration.md) and [native fixture](../examples/native/README.md). +The completed candidate combines the [spec/REA foundation](https://github.com/specdog/dotdog/pull/332), [spec-check boundaries](https://github.com/specdog/dotdog/pull/337), [path optimization](https://github.com/specdog/dotdog/pull/338), [bounded type module](https://github.com/specdog/dotdog/pull/339) and [final boundary review](https://github.com/specdog/dotdog/pull/340). The full local suite passes 133 tests/2,102 assertions. Hosted checks cover Linux Node 22/24/26, macOS/Windows Node 24, Bun 1.3.14/1.4.4 and pinned Spec Kit 0.12.0/1.2.5. Each changed head must pass its own checks. -The [type research](https://github.com/specdog/specdog.github.io/pull/66) preserves its 62-check research checkpoint, including native TypeScript 7.1 beta probes. The candidate now implements a separate bounded 7.0.2 adapter with real compiler/graph integration tests, rather than treating the old 5/6 extractor as compatible. Reference builds remain unsupported. No beta compiler is required, and a compiler pass does not establish requirement satisfaction. +Fresh forward/backward Ghidra fixture checks preserve the target digest without executing it. Actual Codex app-server checks exercise discovery, command execution, edit refresh and removal discovery; actual Claude Code checks exercise skill/MCP discovery, settings preservation and removal. A model-driven Claude invocation/edit-refresh run remains unverified. Internal driver/state/log files stay outside the public package. + +The [type research](https://github.com/specdog/specdog.github.io/pull/66) preserves its separate 62-check checkpoint and historical compiler probes. The production candidate uses the tested 7.0.2 interface, not the incompatible 5/6 extractor or a required beta compiler. Reference builds remain unsupported; compiler success is not requirement proof. [Source-review dispositions](v1-security-audit.md), [measured workflow comparison](path-performance.md), [migration](v1-migration.md) and the [native fixture](../examples/native/README.md) retain the implementation evidence and limitations. Freeze features before final review. Reconcile findings against the complete release diff. A failed or skipped required gate is not a release pass. Do not hide failures by reducing coverage or replacing real integrations with mocks. A SolidState wrapper pass establishes only what its underlying check exercised. ## Outstanding launch gates -- Complete current-head cross-platform/package and boundary review for the #333 implementation; broader compiler/reference support is not a 1.0 prerequisite. -- Complete #334 code/bloat audit and #335 measured optimization report. -- Complete actual Codex/Claude host acceptance and final security review in #336. +- Reconcile current-head cross-platform/package results with the completed source review; broader compiler/reference or semantic/VSA research is not a 1.0 prerequisite. +- Resolve the unverified model-driven Claude invocation/edit-refresh gate explicitly; do not relabel deterministic host checks as a model turn. - Freeze the final candidate, verify minimum-runtime/package behavior and resolve prerelease feedback. - Verify npm trusted-publisher configuration and obtain release approval. Tests of the publishing script do not verify registry permissions. The release remains unmerged and unpublished until these gates are complete. Existing live-provider behavior requires real-target evidence before making live-integration claims; it is not a cloud-provisioning prerequisite for the scoped graph workflows. -The separate TypeScript 7.0.2 CLI probe checked valid → invalid → repaired code, compiler-emitted signatures, a re-export and declaration maps without changing the project configuration. The current packaged candidate passed clean-consumer checks on Node 22.12.0, Node 24, Node 26 and Bun. These bounded checks do not establish production type integration, complete audit coverage or a measured speedup. +Historical declaration-emission probes are distinct from the implemented read-only native adapter and from final archived package bytes. Runtime/host and performance checks establish only their stated cases, not complete correctness or end-to-end model productivity. ## 6. Release integrity and approval diff --git a/docs/v1-security-audit.md b/docs/v1-security-audit.md index f3a177a..1642a2b 100644 --- a/docs/v1-security-audit.md +++ b/docs/v1-security-audit.md @@ -1,85 +1,53 @@ --- layout: default -title: Dotdog 1.0 security and release sweep +title: Dotdog 1.0 security and release review --- -# Dotdog 1.0 security and release sweep +# Dotdog 1.0 security and release review -Date: 2026-10-29. Scope: the unpublished npm/Bun 1.0 candidate in PR #332, following the [0.9.0 artifact audit](npm-0.9-audit.md). This is a source review plus local regression testing, not a third-party penetration test or a safety certification. +Reviewed 2026-11-01 for the first 1.0.0 npm/Bun release. Scope: CLI registrations/aliases, saved graph formats and MCP consumers, spec import/checks, repository/workspace boundaries, generated writes/locks, optional compiler execution, hooks, provider dispatch and package publishing. This is a source review with regressions and integration checks, not an independent penetration test or a guarantee of bug freedom. -## Confirmed findings and repairs +## Findings and dispositions -| Finding | Observed failure / precondition | Repair and regression | -| --- | --- | --- | -| Dangling output symlink | A repository symlink to an absent external file passed path resolution | Detect dangling symlink components; refuse writes through symlinked output paths | -| Generated-file overwrite | `map` followed an existing `repo.dag` symlink and overwrote an external fixture | Check each generated/cache/compiled destination, not only its directory | -| Git inventory escape | A tracked source directory replaced with an external symlink was still included | Resolve and reject symlinked inventory paths before reading/hashing | -| Forged hook ownership | A crafted hook manifest could name and hash an unrelated repo file; remove deleted it | Validate the expected Git/Claude target and the exact installed hook identity; preserve edited hooks | -| Parser denial of service | `[1/1]` steps and non-table pipe lines stalled compilation | Guarantee parser progress; reject unclosed plain fences; keep fenced headings out of section splitting | -| Unbounded MCP input | Line buffering had no explicit size limit | Stream requests sequentially, enforce a 1 MiB line limit and respect output backpressure | -| Provider dispatch guesses | Railway selected discovered tools by substring; Cloudflare used literal `:account_id`; remote MCP probes lacked auth | Remove the unused hand-written external MCP client and probes; use explicit documented read-only API routes | -| Railway query construction | Resource text was interpolated into GraphQL source | Use a fixed query with variables; use service IDs and token-specific headers | -| Provider false passes | Supabase project fallback ignored requested tables; provider/entity filters did not intersect | Report tables unverified, intersect filters, and fail strict live checks for non-pass results | -| Endpoint false passes | Expected values/types were ignored; missing-body handling was truthiness-based | Compare expected JSON recursively, including false/zero/null and arrays; extra object keys remain allowed | -| Endpoint resource handling | Timeout was cleared before the body finished; failure paths could double-count | Keep timeout through body reads, cap JSON bodies at 1 MiB, reject redirects/embedded URL credentials, count once | -| Ambiguous graph references | Duplicate labels could resolve to whichever node was last/first | Prefer exact IDs; reject ambiguous labels and expose candidate IDs | -| Stale extractor cache | Cache key did not include package/parser upgrades | Include package, parser and extraction-schema versions in the key | - -The symlink/hook regressions were run before repair and all four failed; after repair they passed while external evidence bytes and unrelated files were preserved. Parser and provider/contract cases have dedicated regressions. These are local malicious-checkout scenarios, not evidence of an observed compromise in a user's installation. - -## Dependencies and release integrity - -The original development tree had known advisory matches, including SDK 1.29.0 and transitive HTTP/schema packages. SDK is now 1.32.2. Explicit root overrides select patched compatible transitive packages where ordinary Bun updates retained vulnerable resolutions. Babel stays on 7.29.11 because Babel 8's engine range excludes the supported Node 22.12 baseline. Chalk is updated to 6.0.1. - -`bun audit --json` returned `{}` after these changes. This is an advisory-database snapshot, not malware detection or proof that all dependencies are safe. The shipped CLI remains self-contained with no declared runtime npm dependencies; SDK/AJV and their HTTP stacks are development/test dependencies, not bundled runtime services. Babel, Chalk and Commander are bundled and retain third-party notices. - -CI now includes a scheduled and dependency-change advisory audit, frozen lockfile installation, pinned action revisions, packed-consumer checks and a real MCP SDK stdio client regression. Dependabot is configured for Bun and GitHub Actions using GitHub's [documented Bun ecosystem support](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference). The npm publish job checks tag/version agreement, tests/builds the candidate, requests provenance and requires its tagged commit to belong to main history. Trusted-publisher/account configuration and branch protection remain external settings; this PR does not prove they are enabled. - -## Boundaries and remaining gaps - -- `serve` is local stdio, not an HTTP service. Graph content and imported descriptions are untrusted data, not permission or agent instructions. -- Graph reads/imports use a 32 MiB input cap, 100,000-node/500,000-edge normalization limits; MCP combined graph text is capped at 128 MiB. These are finite processing limits, not CPU/memory guarantees. Local repository mapping and all legacy command outputs are not globally quota-managed. -- Generated writes and inventory traversal reject static symlink escapes. Generated writes now use fsync plus same-directory atomic replacement, preserving other owners of hard-linked files; cooperating refresh/map/compile writers use an ownership lock with dead-process recovery. No claim is made of race-free multi-user filesystem isolation; an OS sandbox remains authoritative. -- Credential-file exclusions and output redaction are best-effort. Specs, source, filenames and derived graphs can contain private data. Review exports; do not put credentials in graph properties. -- `live` explicitly contacts spec-defined HTTP(S) URLs, including permitted local endpoints. Review untrusted contracts before running it. Provider calls use fixed API origins and reject redirects; AWS uses the installed CLI and its existing credential configuration. No blanket SSRF-proof claim is made. -- Provider tests use mocked API responses and request assertions. Live cloud accounts, current provider permissions, rate limits and modern client UI sessions remain unverified. Hosted Windows checks passed at `0569319` alongside macOS/Linux; later commits must pass their own matrix. -- REA import passed source-schema fixture validation and a real Ghidra 12.1.4 → REA 6.8.0 → Dotdog fixture on macOS arm64; broader target/host coverage remains unverified. See [native fixture](../examples/native/README.md). No separate REA provider was installed or registered. -- Embodied support checks supplied evidence relationships only. It discovers neither missing real-world hazards nor measurement quality and grants no physical authority. - -See [migration](v1-migration.md), [peer research](graph-peer-research.md) and [embodied evidence](embodied-systems.md) for supported behavior and explicit limits. The candidate remains unmerged and unpublished until separately released. +Code paths below are relative to `packages/dotdog/src/`. -## Scoped gap repair - -The workspace-boundary repair at `22b0b7e` validates malformed nested input before registry construction and removes the resolver's unchecked JSON-to-config assertion. Success-only typed data passes real `strict`/`exactOptionalPropertyTypes` compiler checks; invalid-result data access is rejected with TS2339. No runtime schema dependency was added. - -`path --dag` previously bypassed repository and file-size checks. It now uses the shared safe reader; a regression confirms that an external graph cannot be returned. Traversal results retain supplied coverage and node provenance, disclose search boundaries, and fail explicitly when scope metadata cannot fit the requested token budget. - -Review of REA 6.8.0's installed request/output contracts and traversal implementation found that a bare call-graph export omits its producer direction. Imports now require an explicit forward/backward declaration and orient caller evidence correctly; the declaration is not independent verification of the producer request. The real source-fixture check passed forward and backward one-hop paths through Ghidra/REA and the built CLI, without executing or changing the target binary. - -The full local candidate suite passed 116 tests; dependency advisory output was `{}`. These checks and the focused boundary review do not complete the final release audit, current-head hosted matrix or the pending type-context module. Temporary full provider evidence remains private. No merge or publication occurred. - -## Local verification record - -### Path-search optimization verification - -The unreleased 1.0.0 candidate replaces per-node path-history copies with parent links and skips adjacency construction for zero-hop results. The full local suite passed 122 tests, 2,019 assertions and one snapshot after this change. The independent distance oracle also checks returned path continuity and filtered edge verbs. Two synthetic timing comparisons, with reversed implementation order on replay, retain identical result hashes; the [report](path-performance.md) explicitly distinguishes measured path improvements from ordinary MCP queries with no demonstrated improvement. This is not completion of the broader optimization or release audit. +| Boundary | Finding and disposition | Verification | +| --- | --- | --- | +| Filesystem writes/inventory | **Fixed:** static symlink escapes, dangling output symlinks, redirected Git inventory and hard-link truncation. Generated replacement uses fsync and atomic rename; cooperating graph writers have ownership locks and dead-process recovery. | `security.test.ts`, `writes.test.ts`; external fixture bytes remain unchanged; concurrent writers fail explicitly. | +| Parsing/spec checks | **Fixed:** parser non-progress on step/table lines, graph reads bypassing the size guard and ambiguous reference labels passing checks. Exact IDs take precedence. | Parser/security/release-audit regressions; ambiguous and oversized inputs fail without changing authored plans. | +| Workspace input | **Fixed:** malformed nested JSON reached unchecked typed data. Shape/reference checks precede registry construction; only successful parser results expose typed data. | Nested-input cases and real strict/exact-optional compiler checks in `workspace.test.ts`. | +| Graph/query contracts | **Fixed:** arbitrary-node matches for punctuation/Unicode, ambiguous duplicate labels, omitted-candidate flags, lost node provenance and scope-free token errors. Ambiguity candidates use exact IDs and disclose truncation. | Independent distance oracle, context token vectors/budgets, changed/deleted/corrupt graph cases and CLI/MCP schema regressions. | +| MCP transport | **Fixed:** unbounded line buffering. Local stdio handles requests sequentially, enforces a 1 MiB line cap and output backpressure, and validates tool arguments. | Real SDK stdio discovery/invocation; all eleven tool contracts and legacy/modern protocol cases. | +| REA import | **Fixed:** bare exports omitted producer direction and could reverse caller meaning. Require the declared direction; retain binary/export identity, coverage and evidence. | Fresh SolidState-owned Ghidra forward/backward fixture checks; both one-hop paths pass, binary digest unchanged, target never executed. | +| Optional types | **Reviewed:** exact TypeScript 7.0.2 project compiler, original options/diagnostics, no emit/build writes, bounded Node worker and process-tree cleanup. Saved evidence survives generic import/MCP. | Valid → TS2322 → repaired, inherited JSONC/aliases, repeated names, overloads/unions, Unicode, limits, unsupported inputs and timeout/child cleanup. Coverage remains partial. | +| Skills/hooks | **Fixed:** forged ownership could remove unrelated files; malformed Claude settings could falsely report installation. Validate owned targets and mutation shape; preserve edited skills/hooks and unrelated settings. | Pre-repair failures then passing regressions; idempotence, staged-index checks and actual-host discovery/removal checks. | +| Live/provider operations | **Fixed:** guessed remote MCP dispatch, literal provider identifiers, interpolated GraphQL, ignored filters and false endpoint passes. Use fixed origins/variables, reject redirects, bound response bodies/timeouts and fail strict checks on unverified results. | Request/response regressions in `providers.test.ts` and endpoint contract tests. Live account/resource permissions are not established by mocked requests. | +| Release integrity | **Strengthened:** require tag/version agreement and a main-history commit; manifest records source commit, file list and archive hashes. Publisher refuses mismatched source commits or tampered bytes and publishes the checked archive with provenance. | Negative commit/digest regressions, clean-consumer checks and workflow review. Registry authorization/provenance still require the actual publishing result. | +| Bloat/compatibility | **Removed:** unused legacy `@spec/*` packages, unwired keyword/MCP code, scratch parser copies, obsolete scripts and invalid historical-log benchmark machinery. Retain supported aliases with explicit limitations. Share existing parser chunks rather than duplicate bundled code. | Caller/package inventory, command/legacy-format regressions and package allowlist. No mandatory runtime npm dependency or service was added. | -### Spec-check follow-up +## Verification record -The spec-check repair at `743a1bb` closes two additional gaps in `spec/checks.ts`. Scenario/reference diagnostics previously read graphs without the shared size/type guard, and reference mappings accepted duplicate labels without resolving a unique entity. Both now use `readGraphText`; mappings prioritize exact IDs and reject ambiguous labels. Two regressions failed before repair and passed afterward, including exact-ID precedence and unknown entities. These lexical diagnostics still do not establish graph freshness or semantic correctness; migration guidance now states that distinction explicitly. +The full local candidate suite passes **133 tests, 2,102 assertions and one snapshot**, plus lint, validate/doctor, frozen dependency installation and package checks. The [release review PR](https://github.com/specdog/dotdog/pull/340) tracks current-head Linux Node 22/24/26, macOS/Windows Node 24 and Bun 1.3.14/1.4.4 checks, Spec Kit compatibility and final artifact evidence. Historical checkpoints are not relabeled as results for new bytes. -Local verification passed 118 tests, 566 assertions and one snapshot, plus typecheck/build, frozen install, validate/doctor, extension/package checks and the Node 26/Bun packed-consumer check. A built-CLI fixture returned nonzero for ambiguous references and an oversized scenario graph, accepted an exact ID and preserved its plan bytes. Hosted checks for this revision and the final release audit remain separate gates. +Actual Codex app-server checks cover project skill discovery, command invocation, edit refresh, protected agent configuration and fixture-owner removal discovery. Actual Claude Code checks cover skill discovery, stdio MCP connection, hook removal, unrelated-settings preservation and skill removal discovery. Model-driven Claude invocation/edit refresh remains unverified; deterministic host checks are not a model-output evaluation. -A separate TypeScript 7.0.2 probe confirmed two adapter-plan risks: an existing `declarationDir` can bypass an `outDir`-only temporary destination, and `stripInternal` can omit a type still referenced by an emitted public signature. Explicit inspection-only settings contained declarations and retained that type in the probe. The production adapter must record overrides, contain every output and expose partial dependencies; it is not implemented by this repair. See the [compiler option reference](https://www.typescriptlang.org/tsconfig/#stripInternal) and #333. No compiler framework or dependency was added. +The published 0.9.0 package also passed the required validation dogfood check. Its registry metadata contains provenance, but that does not prove authorization for a future release. No local package test constitutes npm publication. -### Earlier checkpoints +## Dependencies and licenses -The path-boundary follow-up at `d94a8f4` adds regressions for arbitrary-node selection by unmatched punctuation/Unicode queries, unbounded/duplicate-label path ambiguity responses and Windows absolute origin paths retained on POSIX hosts. All three reproduced before their repairs. Exact candidate IDs are capped at 100 with explicit truncation; relative origin paths remain intact. An independent all-pairs-distance oracle also exercises directed cyclic graphs, verb filters, hop limits, zero-hop paths and retained edge evidence. Arbitrary graph properties/evidence are not globally redacted. +`bun audit --json` returned `{}` for the frozen candidate dependencies. This is an advisory snapshot, not malware detection or proof of complete safety. SDK 1.32.2 and patched transitive resolutions are development/test dependencies, not a hosted runtime service. -The initial consolidated suite passed with 96 tests, 391 assertions and one snapshot. Hosted CI status is recorded in PR #332. Typechecking, build, frozen install, skill validation, extension manifest, real demo, and Dotdog's own validate/check/doctor/status checks passed. Packed consumer checks passed under Node 22.12.0, 24.22.1, 26.8.1 and Bun 1.3.14, including a synthetic embodied evidence success/tamper-failure case. That earlier candidate tarball measured 181,077 bytes; it was larger than the original 0.9 artifact and no compression improvement is claimed. +Bundled Babel parser, Commander, Chalk and gpt-tokenizer/o200k_base license notices ship in `THIRD_PARTY_NOTICES.md`. The project compiler is consumer-installed and not bundled. Package inspection excludes node_modules, tests, private state and raw test evidence. Two unused imports were removed without changing emitted bundle bytes. -Follow-up security finding: a generated output hard-linked to an external fixture was truncated before atomic-write repair. The regression now preserves the external bytes. A concurrent writer is rejected; killing the owning process leaves a lock that the next graph refresh recovers. These cases were tested locally; Windows gate results are tracked in the PR. +## Accepted limitations -The retrieval follow-up passed 102 tests, 420 assertions and one snapshot locally, plus typecheck/build and own validate/doctor/check/status. A same-size graph edit with restored timestamps updates the cached relationships and names; invalid graphs evict their previous indexes. The content-read and normalization limits are unchanged. `bun audit --json` again returned `{}`. The newly packed 182,795-byte candidate passed the retained-artifact Node 26.8.1/Bun checks with SHA-256 `973ef8ebb260f1b6f6b1794a9c41b4ab2722b35c09ab200cf6c2792ee13cec83`. Earlier runtime/host results are not relabeled as checks of these new bytes. The [retrieval report](retrieval-benchmarks.md) distinguishes measured latency/token counts from untested semantic/VSA claims. +- Saved graphs describe supplied/observed facts, not requirement satisfaction, complete semantic closure or every runtime effect. Missing edges and bounded negative searches do not prove independence. +- Graph input/normalization, context, MCP and compiler bounds are finite processing limits, not global peak-memory or CPU guarantees. [Measured performance](path-performance.md) distinguishes fixtures, startup, output bytes and OS-reported memory from general speed claims. +- Static path guards and atomic replacement are not race-free multi-user filesystem isolation. Malformed/foreign-host writer locks require inspection rather than guessed ownership. +- Source/config/compiler identity is not authenticity. TypeScript configuration can weaken checks; trusted project compiler code is executable. Re-inspect after project/compiler/dependency changes; saved audits cannot discover new or unloaded files. +- Credential exclusions/redaction are best-effort. Source, signatures, filenames, authored text and arbitrary graph properties can contain sensitive data; review exports before sharing. Imported strings are data, never permission or agent instructions. +- Live endpoint checks intentionally contact reviewed spec-defined URLs, including local endpoints. Real cloud accounts, provider permissions/rate limits and all client/model versions are not covered by fixture tests. They are not prerequisites for local spec/REA/type graph workflows. +- The existing optional evidence profile does not add a simulator, device operation or cloud prerequisite. It does not discover omitted physical hazards, establish measurement quality or authorize actuation. +- Feature review, publication authorization and successful registry deployment are separate. Final source/artifact/provenance and post-publication install results remain authoritative; never infer deployment from a green build. -Hosted follow-up logs exposed forced Node 24 execution of deprecated Node 20 action runtimes. After checking upstream release notes, manifests and resolved commit identities, workflows now pin [checkout 7.0.1](https://github.com/actions/checkout/releases/tag/v7.0.1) (`3d3c42e5aac5ba805825da76410c181273ba90b1`) and [setup-node 7.1.0](https://github.com/actions/setup-node/releases/tag/v7.1.0) (`949feb2413d6458794dcd2491c4babbbce0c15c1`), both native Node 24 actions. Checkout keeps `persist-credentials: false` and does not opt into unsafe fork checkout; setup-node explicitly disables automatic package-manager caching. Its removed dummy auth token is not needed by the intended npm OIDC publisher. Hosted PR checks verify the workflows they execute; actual publication/extension-release workflows remain unexecuted, and older self-hosted runners are not claimed supported. +See [migration](v1-migration.md), [release gates](v1-release-plan.md) and [native fixture](../examples/native/README.md). diff --git a/llms.txt b/llms.txt index 70005cf..4586ac8 100644 --- a/llms.txt +++ b/llms.txt @@ -13,4 +13,4 @@ Run `dotdog refresh --if-stale`, query the relevant project, and verify cited so - [Security audit](https://specdog.github.io/dotdog/v1-security-audit): Reproduced repairs, dependency updates and unverified boundaries. - [Peer research](https://specdog.github.io/dotdog/graph-peer-research): Dated high-star graph/context comparison. -- [Embodied evidence](https://specdog.github.io/dotdog/embodied-systems): Advisory artifact and relationship checks, not device control. +- [Type contracts](https://specdog.github.io/dotdog/type-contracts): Optional selected TypeScript 7.0.2 contracts, diagnostics and bounded graph references. diff --git a/packages/dotdog/CHANGELOG.md b/packages/dotdog/CHANGELOG.md index bc2239d..188fb24 100644 --- a/packages/dotdog/CHANGELOG.md +++ b/packages/dotdog/CHANGELOG.md @@ -2,6 +2,9 @@ ## 1.0.0 — Unreleased +- Reject malformed Claude hook settings without overwriting them; disclose omitted ambiguity candidates with exact IDs in graph/MCP context errors. +- Bind verified release archives to source commits and retain package file manifests; share parser chunks and defer tokenizer loading without adding runtime dependencies. + - Add opt-in selected TypeScript 7.0.2 contract inspection with original project diagnostics, bounded declared-type references and retained compiler/config/source evidence; no declaration emit or automatic compiler installation. - Store BFS parent links instead of copying full path histories for each queued node; skip adjacency construction for zero-hop paths. diff --git a/packages/dotdog/README.md b/packages/dotdog/README.md index 8888046..92f8315 100644 --- a/packages/dotdog/README.md +++ b/packages/dotdog/README.md @@ -139,7 +139,7 @@ dotdog graph audit --dag .doghouse/imported/system.dag --profile evidence --json `status` is read-only and exits nonzero when graphs are stale or absent. `scenario-check` checks one named Scenario/Flow for lexical compiled-entity references. `reference-check` checks explicit Verify file/property mappings without writing human plans. None proves application correctness. `staleness`, `simulate` and `verify` are deprecated compatibility names; `verify --init` is retired. -`graph audit` checks recorded artifact hashes, timestamps and results. Its optional embodied profile reports missing asset/requirement/sensor/actuator/hazard links. It does not operate hardware, run simulations or certify safety. See the embodied evidence guide for the exact graph conventions. +`graph audit` checks recorded artifact hashes, timestamps and results. This establishes artifact identity and reported traceability, not requirement satisfaction or runtime correctness. ## Limits and migration @@ -152,7 +152,7 @@ dotdog graph audit --dag .doghouse/imported/system.dag --profile evidence --json See [retrieval measurements and superposition assessment](https://github.com/specdog/dotdog/blob/main/docs/retrieval-benchmarks.md) for the controlled benchmark, exact tokenizer baseline and remaining evaluation limits. -See [security audit](https://github.com/specdog/dotdog/blob/main/docs/v1-security-audit.md), [peer research](https://github.com/specdog/dotdog/blob/main/docs/graph-peer-research.md), [embodied evidence](https://github.com/specdog/dotdog/blob/main/docs/embodied-systems.md), [migration](https://github.com/specdog/dotdog/blob/main/docs/v1-migration.md), [audit and research](https://github.com/specdog/dotdog/blob/main/docs/npm-0.9-audit.md), and [integrations](https://github.com/specdog/dotdog/blob/main/docs/integrations.md). The independent Rust port remains in PR #330; npm/Bun delivery is not being replaced by it. +See [security review](https://github.com/specdog/dotdog/blob/main/docs/v1-security-audit.md), [migration](https://github.com/specdog/dotdog/blob/main/docs/v1-migration.md), and [integrations](https://github.com/specdog/dotdog/blob/main/docs/integrations.md). ## Development diff --git a/packages/dotdog/src/infra/verify.ts b/packages/dotdog/src/infra/verify.ts index 18d659e..c3e889e 100644 --- a/packages/dotdog/src/infra/verify.ts +++ b/packages/dotdog/src/infra/verify.ts @@ -2,7 +2,7 @@ // Dispatches to explicit read-only provider checks; output redaction is best-effort. import { readFileSync, existsSync } from 'fs'; -import { join, resolve } from 'path'; +import { join } from 'path'; import { listRepoFiles } from '../map/repoMapper'; import { resolveUserPath } from '../workspace/paths'; import { redactSecrets } from '../workspace/redact'; diff --git a/packages/dotdog/src/types/type-worker.ts b/packages/dotdog/src/types/type-worker.ts index 351d59e..64fddc6 100644 --- a/packages/dotdog/src/types/type-worker.ts +++ b/packages/dotdog/src/types/type-worker.ts @@ -1,7 +1,7 @@ import { createRequire } from 'module'; import { createHash } from 'crypto'; import { readFileSync, readSync, statSync } from 'fs'; -import { basename, dirname, isAbsolute, relative, resolve, sep } from 'path'; +import { basename, dirname, isAbsolute, relative, sep } from 'path'; import { pathToFileURL } from 'url'; import { parseExpression } from '@babel/parser'; import { normalizeGraph } from '../graph/model'; From ededd6eeb6adb107b85cb7e69d9764126ddcc7cf Mon Sep 17 00:00:00 2001 From: logohere <69400476+logohere@users.noreply.github.com> Date: Sun, 1 Nov 2026 03:45:51 -0500 Subject: [PATCH 5/5] chore: prepare verified 1.0.0 release metadata and artifact gates --- .github/workflows/publish.yml | 33 ++++++++++++++++++- CHANGELOG.md | 2 +- README.md | 6 ++-- docs/index.md | 6 ++-- docs/type-contracts.md | 4 +-- docs/v1-migration.md | 2 +- docs/v1-release-plan.md | 6 ++-- docs/v1-security-audit.md | 2 +- packages/dotdog/CHANGELOG.md | 2 +- packages/dotdog/README.md | 6 ++-- .../dotdog/__tests__/release-audit.test.ts | 9 ++++- 11 files changed, 55 insertions(+), 23 deletions(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 2d293f9..424cf22 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -37,6 +37,37 @@ jobs: - run: bun run build - run: node scripts/check-pack.mjs - name: Pack once and verify the release artifact - run: node scripts/check-release.mjs --output "$RUNNER_TEMP/dotdog-release" + run: | + node scripts/check-release.mjs --output "$RUNNER_TEMP/dotdog-release" + echo "DOTDOG_RELEASE_ARCHIVE=$RUNNER_TEMP/dotdog-release/$(node -p "require(process.env.RUNNER_TEMP + '/dotdog-release/release.json').artifact")" >> "$GITHUB_ENV" + - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 + with: + package-manager-cache: false + node-version: '22.12.0' + - name: Verify the same archive on the minimum Node runtime + run: node scripts/check-release.mjs --tarball "$DOTDOG_RELEASE_ARCHIVE" + - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 + with: + package-manager-cache: false + node-version: '26' + - name: Verify the same archive on Node 26 + run: node scripts/check-release.mjs --tarball "$DOTDOG_RELEASE_ARCHIVE" + - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 + with: + package-manager-cache: false + node-version: '24' + registry-url: 'https://registry.npmjs.org' + - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 + with: + bun-version: '1.4.4' + - name: Verify the same archive on current Bun and publishing Node + run: node scripts/check-release.mjs --tarball "$DOTDOG_RELEASE_ARCHIVE" + - name: Retain the checked archive and source manifest + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 + with: + name: dotdog-${{ github.ref_name }} + path: ${{ runner.temp }}/dotdog-release/* + if-no-files-found: error + retention-days: 30 - name: Publish only the verified artifact run: node scripts/publish-release.mjs "$RUNNER_TEMP/dotdog-release/release.json" diff --git a/CHANGELOG.md b/CHANGELOG.md index f2bd02e..6acea72 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## 1.0.0 — Unreleased +## 1.0.0 — 2026-11-01 - Reject malformed Claude hook settings without overwriting them; disclose omitted ambiguity candidates with exact IDs in graph/MCP context errors. - Bind verified release archives to source commits and retain package file manifests; share parser chunks and defer tokenizer loading without adding runtime dependencies. diff --git a/README.md b/README.md index e98c7cf..0e1caf3 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,9 @@ Local-first spec and code graphs for coding agents. Keep human intent, observed implementation, and imported analysis evidence distinct and queryable. -**1.0 development:** this branch prepares the next major release. The published npm `latest` version audited for this update was 0.9.0. No 1.0 release has been published by this change. - ## Install -These commands install the published stable package. The examples on this branch describe the unreleased 1.0 candidate; build this checkout using [Development](#development) to try them before publication. +These commands install the stable package. This guide covers Dotdog 1.0. ```sh npm install -g dotdog @@ -100,7 +98,7 @@ The server supports legacy initialization revisions 2024-11-05, 2025-06-18 and 2 ## Selected type contracts -The unreleased candidate also supports opt-in `types inspect` for selected TypeScript 7.0.2 contracts, compiler diagnostics and bounded type-reference graphs. See [type contracts](docs/type-contracts.md) for built-checkout commands, requirements and limits. No compiler is auto-installed, and no MCP query executes one. +Dotdog 1.0 supports opt-in `types inspect` for selected TypeScript 7.0.2 contracts, compiler diagnostics and bounded type-reference graphs. See [type contracts](docs/type-contracts.md) for commands, requirements and limits. No compiler is auto-installed, and no MCP query executes one. ## REA / Ghidra evidence diff --git a/docs/index.md b/docs/index.md index 3153885..6d53e99 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,11 +7,9 @@ title: Dotdog Local-first spec and code graphs for coding agents. Keep human intent, observed implementation, and imported analysis evidence distinct and queryable. -**1.0 development:** this branch prepares the next major release. The published npm `latest` version audited for this update was 0.9.0. No 1.0 release has been published by this change. - ## Install -These commands install the published stable package. The examples on this branch describe the unreleased 1.0 candidate; build this checkout using [Development](#development) to try them before publication. +These commands install the stable package. This guide covers Dotdog 1.0. ```sh npm install -g dotdog @@ -105,7 +103,7 @@ The server supports legacy initialization revisions 2024-11-05, 2025-06-18 and 2 ## Selected type contracts -The unreleased candidate also supports opt-in `types inspect` for selected TypeScript 7.0.2 contracts, compiler diagnostics and bounded type-reference graphs. See [type contracts](type-contracts.md) for built-checkout commands, requirements and limits. No compiler is auto-installed, and no MCP query executes one. +Dotdog 1.0 supports opt-in `types inspect` for selected TypeScript 7.0.2 contracts, compiler diagnostics and bounded type-reference graphs. See [type contracts](type-contracts.md) for commands, requirements and limits. No compiler is auto-installed, and no MCP query executes one. ## REA / Ghidra evidence diff --git a/docs/type-contracts.md b/docs/type-contracts.md index ce8f6a7..00fd39d 100644 --- a/docs/type-contracts.md +++ b/docs/type-contracts.md @@ -5,11 +5,11 @@ title: Selected type contracts # Selected type contracts -The unreleased 1.0.0 candidate can inspect one exported TypeScript contract and its bounded declared-type references. Specs retain intended behavior; compiler checks enforce encoded constraints; graphs retain relationships and evidence. None substitutes for behavioral tests or runtime input validation. +Dotdog 1.0 can inspect one exported TypeScript contract and its bounded declared-type references. Specs retain intended behavior; compiler checks enforce encoded constraints; graphs retain relationships and evidence. None substitutes for behavioral tests or runtime input validation. ## Requirements -- Node.js 22.12.0 or newer and a built Dotdog checkout, or the package after 1.0 publication. +- Dotdog 1.0 and Node.js 22.12.0 or newer, including when invoking type inspection through Bun. - TypeScript **7.0.2** installed in the consumer project/workspace. Dotdog does not install a compiler or require a beta version. - A selected export/file contained in an explicit project configuration. JSONC, inherited options and compiler-resolved aliases are exercised by the integration tests. diff --git a/docs/v1-migration.md b/docs/v1-migration.md index f8bdcd7..cc30e43 100644 --- a/docs/v1-migration.md +++ b/docs/v1-migration.md @@ -5,7 +5,7 @@ title: Dotdog 1.0 migration # Migrating to Dotdog 1.0 -1.0 is being prepared on the modernization branch. Do not assume an npm tag, Homebrew formula or Spec Kit release asset exists until its release is published. +This guide covers the 1.0 npm/Bun release. Homebrew and Spec Kit extension assets are separately maintained distributions; verify their published versions before installing. ## Distribution diff --git a/docs/v1-release-plan.md b/docs/v1-release-plan.md index 99e5774..810cd51 100644 --- a/docs/v1-release-plan.md +++ b/docs/v1-release-plan.md @@ -95,13 +95,13 @@ The focused [path-search comparison](path-performance.md) measures parent-link B | Compatibility | Supported graph formats, CLI exits, JSON/MCP contracts and removable integrations pass regression checks. User-owned specs/settings are preserved. | | Security | Parser, filesystem, child-process, hook and provider boundaries are reviewed; reproduced findings have regressions. No unresolved high-impact release defects. Advisory scans supplement manual review. | | Runtimes | Linux/macOS/Windows CI passes; clean consumers exercise the packaged CLI on supported Node/Bun runtimes, including the declared Node minimum. | -| Agent hosts | Codex/Claude skill discovery, invocation, edit refresh and removal are verified in the actual hosts. Installed files alone are not sufficient. | +| Agent integrations | Actual-host skill/MCP discovery and removal, CLI command/refresh behavior and settings preservation are verified; installed files alone are insufficient. Model-driven behavior studies are separate from local CLI/MCP release contracts. | | Documentation | Stable installation and development-candidate instructions are distinct. Commands, migration notes, package/extension versions and supported limitations agree. | | Release integrity | Approve the final commit; pack once, retain hashes, test those bytes, resolve prerelease findings and publish only the verified archive with provenance. | ## Implementation status -The completed candidate combines the [spec/REA foundation](https://github.com/specdog/dotdog/pull/332), [spec-check boundaries](https://github.com/specdog/dotdog/pull/337), [path optimization](https://github.com/specdog/dotdog/pull/338), [bounded type module](https://github.com/specdog/dotdog/pull/339) and [final boundary review](https://github.com/specdog/dotdog/pull/340). The full local suite passes 133 tests/2,102 assertions. Hosted checks cover Linux Node 22/24/26, macOS/Windows Node 24, Bun 1.3.14/1.4.4 and pinned Spec Kit 0.12.0/1.2.5. Each changed head must pass its own checks. +The completed candidate combines the [spec/REA foundation](https://github.com/specdog/dotdog/pull/332), [spec-check boundaries](https://github.com/specdog/dotdog/pull/337), [path optimization](https://github.com/specdog/dotdog/pull/338), [bounded type module](https://github.com/specdog/dotdog/pull/339) and [final boundary review](https://github.com/specdog/dotdog/pull/340). The full local suite passes 133 tests/2,124 assertions. Hosted checks cover Linux Node 22/24/26, macOS/Windows Node 24, Bun 1.3.14/1.4.4 and pinned Spec Kit 0.12.0/1.2.5. Each changed head must pass its own checks. Fresh forward/backward Ghidra fixture checks preserve the target digest without executing it. Actual Codex app-server checks exercise discovery, command execution, edit refresh and removal discovery; actual Claude Code checks exercise skill/MCP discovery, settings preservation and removal. A model-driven Claude invocation/edit-refresh run remains unverified. Internal driver/state/log files stay outside the public package. @@ -112,7 +112,7 @@ Freeze features before final review. Reconcile findings against the complete rel ## Outstanding launch gates - Reconcile current-head cross-platform/package results with the completed source review; broader compiler/reference or semantic/VSA research is not a 1.0 prerequisite. -- Resolve the unverified model-driven Claude invocation/edit-refresh gate explicitly; do not relabel deterministic host checks as a model turn. +- Retain the model-driven Claude limitation explicitly; actual host discovery/removal and deterministic CLI/MCP contracts, not a paid model account or model-output study, are the scoped integration gates. - Freeze the final candidate, verify minimum-runtime/package behavior and resolve prerelease feedback. - Verify npm trusted-publisher configuration and obtain release approval. Tests of the publishing script do not verify registry permissions. diff --git a/docs/v1-security-audit.md b/docs/v1-security-audit.md index 1642a2b..bf2b37f 100644 --- a/docs/v1-security-audit.md +++ b/docs/v1-security-audit.md @@ -27,7 +27,7 @@ Code paths below are relative to `packages/dotdog/src/`. ## Verification record -The full local candidate suite passes **133 tests, 2,102 assertions and one snapshot**, plus lint, validate/doctor, frozen dependency installation and package checks. The [release review PR](https://github.com/specdog/dotdog/pull/340) tracks current-head Linux Node 22/24/26, macOS/Windows Node 24 and Bun 1.3.14/1.4.4 checks, Spec Kit compatibility and final artifact evidence. Historical checkpoints are not relabeled as results for new bytes. +The full local candidate suite passes **133 tests, 2,124 assertions and one snapshot**, plus lint, validate/doctor, frozen dependency installation and package checks. The [release review PR](https://github.com/specdog/dotdog/pull/340) tracks current-head Linux Node 22/24/26, macOS/Windows Node 24 and Bun 1.3.14/1.4.4 checks, Spec Kit compatibility and final artifact evidence. Historical checkpoints are not relabeled as results for new bytes. Actual Codex app-server checks cover project skill discovery, command invocation, edit refresh, protected agent configuration and fixture-owner removal discovery. Actual Claude Code checks cover skill discovery, stdio MCP connection, hook removal, unrelated-settings preservation and skill removal discovery. Model-driven Claude invocation/edit refresh remains unverified; deterministic host checks are not a model-output evaluation. diff --git a/packages/dotdog/CHANGELOG.md b/packages/dotdog/CHANGELOG.md index 188fb24..d79b780 100644 --- a/packages/dotdog/CHANGELOG.md +++ b/packages/dotdog/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## 1.0.0 — Unreleased +## 1.0.0 — 2026-11-01 - Reject malformed Claude hook settings without overwriting them; disclose omitted ambiguity candidates with exact IDs in graph/MCP context errors. - Bind verified release archives to source commits and retain package file manifests; share parser chunks and defer tokenizer loading without adding runtime dependencies. diff --git a/packages/dotdog/README.md b/packages/dotdog/README.md index 92f8315..616b629 100644 --- a/packages/dotdog/README.md +++ b/packages/dotdog/README.md @@ -2,11 +2,9 @@ Local-first spec and code graphs for coding agents. Keep human intent, observed implementation, and imported analysis evidence distinct and queryable. -**1.0 development:** this branch prepares the next major release. The published npm `latest` version audited for this update was 0.9.0. No 1.0 release has been published by this change. - ## Install -These commands install the published stable package. The examples on this branch describe the unreleased 1.0 candidate; build this checkout using [Development](#development) to try them before publication. +These commands install the stable package. This guide covers Dotdog 1.0. ```sh npm install -g dotdog @@ -100,7 +98,7 @@ The server supports legacy initialization revisions 2024-11-05, 2025-06-18 and 2 ## Selected type contracts -The unreleased candidate also supports opt-in `types inspect` for selected TypeScript 7.0.2 contracts, compiler diagnostics and bounded type-reference graphs. See [type contracts](https://github.com/specdog/dotdog/blob/main/docs/type-contracts.md) for built-checkout commands, requirements and limits. No compiler is auto-installed, and no MCP query executes one. +Dotdog 1.0 supports opt-in `types inspect` for selected TypeScript 7.0.2 contracts, compiler diagnostics and bounded type-reference graphs. See [type contracts](https://github.com/specdog/dotdog/blob/main/docs/type-contracts.md) for commands, requirements and limits. No compiler is auto-installed, and no MCP query executes one. ## REA / Ghidra evidence diff --git a/packages/dotdog/__tests__/release-audit.test.ts b/packages/dotdog/__tests__/release-audit.test.ts index 87712aa..bc3e8b0 100644 --- a/packages/dotdog/__tests__/release-audit.test.ts +++ b/packages/dotdog/__tests__/release-audit.test.ts @@ -151,13 +151,20 @@ test('embodied evidence checks detect stale, changed, failing and omitted covera test('real MCP SDK connects, discovers schemas, and calls Dotdog over stdio', async () => { const root = fixture(); - writeFileSync(join(root, 'example.dag'), JSON.stringify({ project: 'example', nodes: [{ id: 'a', label: 'A' }], edges: [] })); + writeFileSync(join(root, 'example.dag'), JSON.stringify({ project: 'example', nodes: [{ id: 'a', label: 'A' }, { id: 'b', label: 'B' }], edges: [{ sourceId: 'a', targetId: 'b', verb: 'references' }] })); const transport = new StdioClientTransport({ command: process.execPath, args: [cli, 'serve'], cwd: root, stderr: 'pipe' }); const client = new Client({ name: 'dotdog-regression', version: '1.0.0' }); try { await client.connect(transport); const tools = await client.listTools(); expect(tools.tools).toHaveLength(11); + const Ajv = (await import('ajv/dist/2020')).default, ajv = new Ajv({ strict: false }); + const inputs: Record = { getEntity: { name: 'A' }, traverse: { from: 'A' }, path: { from: 'A', to: 'B' }, search: { q: 'A' }, schema: { entity: 'A' }, context: { q: 'A' }, impact: { from: 'B' }, infraVerify: { summary: true } }; + for (const tool of tools.tools) { + const response = await client.callTool({ name: tool.name, arguments: inputs[tool.name] || {} }); + expect(response.isError).toBe(false); + expect(ajv.compile(tool.outputSchema!)(response.structuredContent)).toBe(true); + } const response = await client.callTool({ name: 'getEntity', arguments: { project: 'example', name: 'A' } }); expect(response.isError).toBe(false); expect(response.structuredContent?.name).toBe('A');