diff --git a/README.md b/README.md index 0a05cb54..f1377695 100644 --- a/README.md +++ b/README.md @@ -712,6 +712,31 @@ structure drift, fixture evals, package dry-run, and high-severity dependency audit. Use `npm run test:mcp`, `npm run test:source-audit`, and `npm run test:release-gates` when checking those surfaces directly. +Phase 22 also wires single-name release gates that fold those checks into one +runner (`scripts/release-gates.mjs`): + +```bash +npm run gate:all # run every named gate +npm run gate:typecheck # node --check + structure drift +npm run gate:tests # unit + MCP + source-audit + trace-policy +npm run gate:truth-table-fresh # CAPABILITY_TRUTH_TABLE.md ≤ 7 days old +npm run gate:mcp-scope-frozen # only the 2 frozen browser_* tools +npm run gate:no-experimental-in-readme-ready-section +``` + +The capability/claim truth table for both `agbrowse` and the `cli-jaw` mirror +lives at [`structure/CAPABILITY_TRUTH_TABLE.md`](structure/CAPABILITY_TRUTH_TABLE.md); +update that file in the same commit as any capability or claim change. + +Strict-migration baseline checks shipped alongside the gates: + +```bash +npm run check:strict-baseline # JSDoc opt-in regression guard +npm run check:module-graph # module dependency graph regression +npm run smoke:bins # published bin entrypoints boot +npm run typecheck # tsc --noEmit on the strict surface +``` + For npm trusted publishing through GitHub Actions, configure npm's trusted publisher for: diff --git a/structure/INDEX.md b/structure/INDEX.md index b891c8a9..7fb2b3a6 100644 --- a/structure/INDEX.md +++ b/structure/INDEX.md @@ -82,5 +82,6 @@ graph LR ## 변경 기록 +- 2026-05-06: strict-migration P02–P51 + Phase 22 머지 이후 `str_func.md` 스냅샷, `commands.md` root command 표(`new-tab`, `tab-close`), `release_gates.md`의 `gate:*` named release gate 표를 동기화했다. capability/claim 진실은 [CAPABILITY_TRUTH_TABLE.md](CAPABILITY_TRUTH_TABLE.md)에 모았다. - 2026-05-05: Phase 11+ claim status를 [phase_status.md](phase_status.md)에 분리해 partial/deferred phase가 완료로 오해되지 않게 했다. - 2026-05-05: `cli-jaw/structure` 패턴을 `agbrowse`에 맞게 축소하지 않고 drift/count 검증 스크립트까지 포함한 source-of-truth 허브로 추가했다. diff --git a/structure/commands.md b/structure/commands.md index cb812572..d29c7b6e 100644 --- a/structure/commands.md +++ b/structure/commands.md @@ -22,7 +22,7 @@ aliases: [agbrowse commands, agbrowse CLI 표면, web-ai commands] | Lifecycle | `start`, `stop`, `status`, `reset` | Chrome CDP lifecycle | | Observe | `snapshot`, `screenshot`, `text`, `get-dom` | DOM/ref/text/screenshot 관찰 | | Act | `click`, `type`, `press`, `hover`, `select`, `check`, `uncheck`, `drag`, `mouse-click`, `move-mouse`, `mouse-down`, `mouse-up` | ref 기반 또는 coordinate 기반 mutation | -| Navigate | `navigate`, `reload`, `resize`, `tabs`, `tab-switch`, `select-tab`, `tab-cleanup`, `scroll` | navigation, viewport, tab 관리 | +| Navigate | `navigate`, `reload`, `resize`, `tabs`, `tab-switch`, `select-tab`, `new-tab`, `tab-close`, `tab-cleanup`, `scroll` | navigation, viewport, tab 관리 (multi-tab create/close 포함) | | Wait | `wait`, `wait-for-selector`, `wait-for-text`, `wait-for` | time, selector, text, legacy ref wait | | Diagnostics | `console`, `network`, `evaluate` | console/network capture와 explicit unsafe JS evaluation | | Web AI | `web-ai` | provider workflow subcommand | @@ -106,4 +106,5 @@ JSON 모드에서는 실패가 parseable envelope로 나온다. 이 shape는 MCP ## 변경 기록 +- 2026-05-06: Phase 9.1 multi-tab의 `new-tab`, `tab-close` 명령을 root command 표에 추가해 README와 일치시켰다. - 2026-05-05: root CLI, web-ai, MCP tool, provider alias, failure envelope, drift 검사 기준을 source-of-truth 문서로 추가했다. diff --git a/structure/release_gates.md b/structure/release_gates.md index 938b959a..353a5d39 100644 --- a/structure/release_gates.md +++ b/structure/release_gates.md @@ -45,6 +45,10 @@ aliases: [agbrowse release gates, agbrowse 릴리즈 게이트, production readi - [ ] `npm run test:mcp` - [ ] `npm run test:source-audit` - [ ] `npm run test:release-gates` +- [ ] `npm run gate:all` (named release gates: typecheck, tests, truth-table-fresh, mcp-scope-frozen, no-experimental-in-readme-ready-section) +- [ ] `node scripts/check-strict-baseline.mjs` +- [ ] `npm run check:module-graph` +- [ ] `npm run smoke:bins` - [ ] `npm run benchmark:trajectory -- --help` - [ ] `npm pack --dry-run` - [ ] `npm publish --dry-run --access public` 또는 preview면 `--tag preview` @@ -63,6 +67,17 @@ aliases: [agbrowse release gates, agbrowse 릴리즈 게이트, production readi | `npm run test:mcp` | MCP protocol/schema/policy tests | Phase 18 ready claim이 실제 tool surface와 일치하는지 확인 | | `npm run test:source-audit` | answer artifact + source audit tests | Phase 17 research/source claim 차단 | | `npm run test:release-gates` | structure drift + count checks | Phase status, command, release claim drift 차단 | +| `npm run gate:all` | Phase 22 named release gates (`gate:typecheck`, `gate:tests`, `gate:truth-table-fresh`, `gate:mcp-scope-frozen`, `gate:no-experimental-in-readme-ready-section`) | capability table freshness, frozen MCP scope, README 라벨 일치를 단일 명령으로 검증 | +| `npm run gate:typecheck` | `node --check` + `check-doc-drift.sh` | 공개 .mjs 진입점 syntax + 구조 문서 일치 | +| `npm run gate:tests` | unit + MCP + source-audit + trace-policy 통합 실행 | 핵심 회귀 suite 한 번에 | +| `npm run gate:truth-table-fresh` | `structure/CAPABILITY_TRUTH_TABLE.md` 7일 이내 갱신 또는 코드 ref 일치 | capability claim drift 차단 | +| `npm run gate:mcp-scope-frozen` | MCP `browser_*` tool 등록 범위가 frozen scope (`browser_snapshot`, `browser_click_ref`)에 머무는지 확인 | 미구현 browser MCP tool 노출 차단 | +| `npm run gate:no-experimental-in-readme-ready-section` | README ready 섹션이 external CDP 등 experimental 표면을 광고하지 않는지 검사 | 라벨 drift 차단 | +| `npm run check:strict-baseline` (`node scripts/check-strict-baseline.mjs`) | strict-migration JSDoc opt-in baseline 회귀 차단 | 이미 strict로 옮긴 파일이 다시 untyped로 돌아가지 않게 한다 | +| `npm run check:module-graph` | `scripts/check-module-graph.mjs` 모듈 의존성 그래프 회귀 검사 | leaf/utility layer 경계 보존 | +| `npm run smoke:bins` | published bin entrypoint smoke (`agbrowse`, `agbrowse-vision-click`) | 패키징 후 bin shim이 부팅하는지 확인 | +| `npm run typecheck` / `typecheck:checkjs` / `typecheck:checkjs-dom` | `tsc --noEmit` (root, JSDoc opt-in, DOM-aware JSDoc opt-in) | strict-migration 진행 표면이 깨지지 않는지 확인 | +| `npm run pack:dry` | `npm pack --dry-run --json` | 패키징 manifest 회귀 확인 | | `npm run benchmark:trajectory` | offline trajectory bundle writer | score가 아니라 sanitized trajectory artifact 생성만 허용 | | `npm run release` | latest release script | clean tree, install, audit, tests, structure gates, fixture evals, diff check, pack, publish dry-run, tag/publish | | `npm run release:preview` | preview release script | preview version, audit, tests, structure gates, fixture evals, diff check, pack, publish dry-run, tag/publish | @@ -80,5 +95,6 @@ aliases: [agbrowse release gates, agbrowse 릴리즈 게이트, production readi ## 변경 기록 +- 2026-05-06: Phase 22 named release gates (`gate:all`, `gate:typecheck`, `gate:tests`, `gate:truth-table-fresh`, `gate:mcp-scope-frozen`, `gate:no-experimental-in-readme-ready-section`)와 strict-baseline / module-graph / bin smoke / pack dry-run 명령을 release path에 추가했다. capability 주장은 [CAPABILITY_TRUTH_TABLE.md](CAPABILITY_TRUTH_TABLE.md)가 단일 source of truth다. - 2026-05-05: MCP/source-audit/release-gate named scripts를 release path에 추가해 public claim gate가 `npm test` 안에 묻히지 않게 했다. - 2026-05-05: Phase 21 release gate 요구를 현재 npm scripts, package dry-run, support label 기준으로 정리했다. diff --git a/structure/str_func.md b/structure/str_func.md index 03218629..2c6bc745 100644 --- a/structure/str_func.md +++ b/structure/str_func.md @@ -16,26 +16,26 @@ aliases: [agbrowse source map, agbrowse str_func, agbrowse 파일 구조] ## 현재 구조 스냅샷 -마지막 측정: 2026-05-05. +마지막 측정: 2026-05-06. | 경로 | 파일 수 | 라인 수 | 역할 | | --- | ---: | ---: | --- | | `bin/` | 2 | 6 | published bin wrapper | -| `skills/browser/` | 8 | 3472 | Chrome lifecycle, CDP connection, refs, tabs, diagnostics | -| `skills/vision-click/` | 3 | 680 | screenshot to coordinate click helper | +| `skills/browser/` | 8 | 4116 | Chrome lifecycle, CDP connection, refs, tabs, diagnostics | +| `skills/vision-click/` | 3 | 831 | screenshot to coordinate click helper | | `skills/web-ai/` | 1 | 365 | bundled agent workflow skill | -| `web-ai/` | 69 | 10899 | provider automation, sessions, MCP, eval, policy, trace | -| `web-ai/context-pack/` | 8 | 583 | file selection, token budget, context rendering | -| `web-ai/eval/` | 5 | 362 | offline provider DOM fixture harness | -| `web-ai/policy/` | 4 | 121 | mutation and content-boundary guardrails | -| `web-ai/trace/` | 4 | 202 | trace ID, redaction, report, writer helpers | -| `scripts/` | 4 | 279 | eval runner and release scripts | -| `test/unit/` | 54 | 5681 | deterministic module tests | -| `test/integration/` | 14 | 1485 | CLI, MCP, policy, provider fixture tests | +| `web-ai/` | 69 | 14783 | provider automation, sessions, MCP, eval, policy, trace | +| `web-ai/context-pack/` | 8 | 802 | file selection, token budget, context rendering | +| `web-ai/eval/` | 5 | 552 | offline provider DOM fixture harness | +| `web-ai/policy/` | 4 | 204 | mutation and content-boundary guardrails | +| `web-ai/trace/` | 4 | 299 | trace ID, redaction, report, writer helpers | +| `scripts/` | 8 | 877 | eval runner, release scripts, named release gates, strict-baseline / module-graph / bin smoke checks | +| `test/unit/` | 55 | 5775 | deterministic module tests | +| `test/integration/` | 15 | 1571 | CLI, MCP, policy, provider fixture tests | | `test/e2e/` | 1 | 50 | browser smoke coverage | | `test/spec/` | 2 | 35 | high-level contract specs | -| `docs/` | 5 | 252 | adoption, trace, production-readiness, comparison, benchmark docs | -| `devlog/` | 61 | 13231 | phased plan, research, implementation notes | +| `docs/` | 8 | 1407 | adoption, trace, production-readiness, comparison, benchmark, EXTERNAL_CDP, migration docs | +| `devlog/` | 104 | 16008 | phased plan, research, implementation notes (incl. strict-migration phases) | `structure/` 자체는 이 문서가 검증 대상으로 삼는 source tree 밖의 문서 허브라서 위 집계에서 제외한다. `verify-counts.sh`는 이 표의 경로별 파일 수와 라인 수를 live source 기준으로 비교한다. @@ -43,25 +43,30 @@ aliases: [agbrowse source map, agbrowse str_func, agbrowse 파일 구조] | 파일 | 라인 수 | 설명 | | --- | ---: | --- | -| `skills/browser/browser.mjs` | 2088 | root CLI parser, Chrome lifecycle, browser primitive commands | -| `skills/browser/tab-manager.mjs` | 371 | CDP target list, create, close, switch | -| `skills/browser/tab-lifecycle.mjs` | 191 | idle cleanup, pinned target, duration parsing | -| `skills/browser/skill-install.mjs` | 280 | bundled skill list/get/install | -| `web-ai/cli.mjs` | 1008 | `web-ai` subcommand parser and command orchestration | -| `web-ai/chatgpt.mjs` | 618 | ChatGPT provider send/poll/query/status | -| `web-ai/gemini-live.mjs` | 620 | Gemini provider send/poll/query/status | -| `web-ai/grok-live.mjs` | 487 | Grok provider send/poll/query/status | -| `web-ai/mcp-server.mjs` | 255 | stdio JSON-RPC MCP bridge | -| `web-ai/tool-schema.mjs` | 114 | MCP and AI SDK schema source | -| `web-ai/answer-artifact.mjs` | 86 | provider poll result artifact normalization | -| `web-ai/source-audit.mjs` | 127 | claim/source coverage audit helper | -| `web-ai/ax-snapshot.mjs` | 235 | compact accessibility snapshot and refs | -| `web-ai/self-heal.mjs` | 384 | deterministic target resolution and validation | -| `web-ai/action-intent.mjs` | 66 | serializable semantic action intent contracts | -| `web-ai/target-resolver.mjs` | 32 | explainable target resolver wrapper | -| `scripts/run-web-ai-eval.mjs` | 51 | provider fixture eval CLI wrapper | -| `scripts/release.sh` | 113 | latest release gate and publish script | -| `scripts/release-preview.sh` | 97 | preview release gate and publish script | +| `skills/browser/browser.mjs` | 2341 | root CLI parser, Chrome lifecycle, browser primitive commands | +| `skills/browser/tab-manager.mjs` | 446 | CDP target list, create, close, switch | +| `skills/browser/tab-lifecycle.mjs` | 273 | idle cleanup, pinned target, duration parsing | +| `skills/browser/skill-install.mjs` | 372 | bundled skill list/get/install | +| `web-ai/cli.mjs` | 1151 | `web-ai` subcommand parser and command orchestration | +| `web-ai/chatgpt.mjs` | 709 | ChatGPT provider send/poll/query/status | +| `web-ai/gemini-live.mjs` | 722 | Gemini provider send/poll/query/status | +| `web-ai/grok-live.mjs` | 558 | Grok provider send/poll/query/status | +| `web-ai/mcp-server.mjs` | 321 | stdio JSON-RPC MCP bridge | +| `web-ai/tool-schema.mjs` | 148 | MCP and AI SDK schema source | +| `web-ai/answer-artifact.mjs` | 153 | provider poll result artifact normalization | +| `web-ai/source-audit.mjs` | 183 | claim/source coverage audit helper | +| `web-ai/ax-snapshot.mjs` | 376 | compact accessibility snapshot and refs | +| `web-ai/self-heal.mjs` | 489 | deterministic target resolution and validation | +| `web-ai/action-intent.mjs` | 99 | serializable semantic action intent contracts | +| `web-ai/target-resolver.mjs` | 45 | explainable target resolver wrapper | +| `scripts/run-web-ai-eval.mjs` | 59 | provider fixture eval CLI wrapper | +| `scripts/release.sh` | 116 | latest release gate and publish script | +| `scripts/release-preview.sh` | 100 | preview release gate and publish script | +| `scripts/release-gates.mjs` | 178 | Phase 22 named release gates (`gate:typecheck`, `gate:tests`, `gate:truth-table-fresh`, `gate:mcp-scope-frozen`, `gate:no-experimental-in-readme-ready-section`) | +| `scripts/check-strict-baseline.mjs` | 135 | strict-mode baseline guard for `tsc --noEmit` JSDoc opt-in surface | +| `scripts/check-module-graph.mjs` | 210 | module dependency graph regression check | +| `scripts/smoke-bins.mjs` | 60 | published bin smoke check used in release gate | +| `scripts/render-trace-report.mjs` | 19 | offline trace report renderer | ## Runtime Flow @@ -107,4 +112,5 @@ sequenceDiagram ## 변경 기록 +- 2026-05-06: 파일 수/라인 수 스냅샷을 strict-migration P02–P51 + Phase 22 머지 이후 기준으로 갱신했고, 새로 추가된 release-gate / strict-baseline / module-graph / bin smoke 스크립트와 EXTERNAL_CDP·migration·traces 문서를 source map에 포함했다. - 2026-05-05: 현재 repo 기준 파일 수, 라인 수, 주요 runtime flow, cli-jaw mirror 기준을 추가했다.