@datafog/fogclaw 0.1.6 → 0.3.0

package/docs/plans/README.md

@@ -1,15 +0,0 @@
-# Plans
-
-Active plans:
-- `docs/plans/active/<slug>-plan.md` (`plan_mode: lightweight|execution`)
-
-Completed plans:
-- `docs/plans/completed/<slug>-plan.md`
-
-All plan files must start with YAML frontmatter and follow `docs/PLANS.md` with required living sections, especially:
-
-- `## Progress` (timestamped checkbox list)
-- `## Surprises & Discoveries`
-- `## Decision Log`
-- `## Outcomes & Retrospective`
-- `## Revision Notes`

package/docs/plans/active/2026-02-16-feat-openclaw-official-submission-plan.md

@@ -1,386 +0,0 @@
----
-slug: 2026-02-16-feat-openclaw-official-submission
-status: active
-phase: plan
-plan_mode: execution
-detail_level: more
-priority: high
-owner: sidmohan
----
-
-# Prepare FogClaw for Official OpenClaw Plugin Submission
-
-This plan is a living document. Keep `Progress`, `Surprises & Discoveries`, `Decision Log`, `Outcomes & Retrospective`, and `Revision Notes` current as work proceeds.
-
-This plan is maintained to the contract in `docs/PLANS.md`.
-
-## Purpose / Big Picture
-
-The objective is to make this repository ready for official OpenClaw submission from the `@openclaw/fogclaw` package line without changing any existing detection behavior.
-
-A reviewer should be able to take a clean checkout of this branch, run the documented evidence commands, and verify three behaviors without guessing: plugin metadata is loadable, guardrail context is applied through the `before_agent_start` flow, and the two tools (`fogclaw_scan`, `fogclaw_redact`) return deterministic, observable outputs.
-
-## Progress
-
-- [x] (2026-02-16T17:40:10Z) P1 [Setup] Read `docs/specs/2026-02-16-feat-openclaw-official-submission-spec.md` and captured all requirements.
-- [x] (2026-02-16T17:40:25Z) P2 [Setup] Read `docs/PLANS.md`, `docs/DOMAIN_DOCS.md`, and `he-plan` instructions.
-- [x] (2026-02-16T17:41:05Z) P3 [Baseline] Ran `npm test` and confirmed current tests are green.
-- [x] (2026-02-16T17:41:10Z) P4 [Baseline] Ran `npm run build` and confirmed TypeScript emits cleanly.
-- [x] (2026-02-16T17:50:00Z) P5 [Scope Alignment] Locked focus to the `@openclaw/fogclaw` branch/package for this iteration and documented `@datafog/fogclaw` as out-of-scope unless requested.
-- [x] (2026-02-16T17:55:00Z) P6 [M1] Validate and normalize package/manifest alignment for the `@openclaw/fogclaw` line (package name + lockfile and public install reference).
-- [x] (2026-02-16T17:55:20Z) P7 [M2] Add deterministic plugin verification commands and reviewer evidence outputs.
-- [x] (2026-02-16T17:55:40Z) P8 [M3] Add PR-facing submission evidence docs in README, including expected pass markers and smoke commands.
-- [x] (2026-02-16T17:53:20Z) P9 [M4] Identify and populate needed domain-doc updates, then finalize handoff sections for transition.
-- [x] (2026-02-16T18:00:10Z) P10 [Gate] Add a non-mocked execution-level plugin contract validation to close `C-1`.
-
-## Surprises & Discoveries
-
-- Observation: The branch now has a consistent package identity for submission scope: `package.json`, `package-lock.json`, and README install command all use `@openclaw/fogclaw`.
-  Evidence: `package.json`, `package-lock.json`, and `README.md` now resolve to `@openclaw/fogclaw` for package-facing guidance.
-
-- Observation: Plugin bootstrap behavior in `src/index.ts` is OpenClaw-compatible and now covered by explicit contract tests.
-  Evidence: `src/index.ts` defines `const fogclaw = { id: "fogclaw", name: "FogClaw", register(api) { ... } }` and `plugin-smoke.test.ts` verifies `api.on("before_agent_start", ...)` plus both tool registrations.
-
-- Observation: A dedicated plugin smoke test now simulates OpenClaw API registration and confirms deterministic hook/tool behavior without requiring external model download.
-  Evidence: `tests/plugin-smoke.test.ts` passes in CI-style unit test execution with all assertions on mock API output.
-
-## Decision Log
-
-- Decision: For this session, treat `@openclaw/fogclaw` as the active publication target.
-  Rationale: You explicitly scoped the work to the latter branch/package and that aligns with official OpenClaw listing expectations.
-  Date/Author: 2026-02-16T17:50:00Z / sidmohan
-
-- Decision: Keep implementation behavior unchanged and do not alter regex/GLiNER detection semantics.
-  Rationale: The objective is submission readiness, and current detection logic is already functionally complete and tested.
-  Date/Author: 2026-02-16T17:50:05Z / sidmohan
-
-- Decision: Do not complete PR transition until domain-doc updates are finished at end of planning.
-  Rationale: `docs/PLANS.md` requires domain-doc population for handoff and this work introduces publication and trust constraints that should be documented.
-  Date/Author: 2026-02-16T17:50:10Z / sidmohan
-
-- Decision: Execute implementation on the dedicated initiative branch `openclaw-plugin-submission` (no default-branch edits) after user explicitly scoped work to this track.
-  Rationale: This respects work isolation while matching your request to focus on the @openclaw branch.
-  Date/Author: 2026-02-16T17:56:00Z / sidmohan
-
-- Decision: Pause release handoff and route back to `he-implement` because a high-priority review finding (C-1) was unresolved.
-  Rationale: Evidence required for submission should include at least one non-mocked plugin contract execution path; current smoke coverage was still mock-only.
-  Date/Author: 2026-02-16T17:59:00Z / sidmohan
-
-- Decision: Re-opened implementation to replace the mocked plugin-smoke contract test with a non-mocked execution-path integration assertion using real plugin registration and scan/redact flow.
-  Rationale: This directly addresses `C-1` and keeps implementation changes scoped to proof quality, not detection semantics.
-  Date/Author: 2026-02-16T18:00:10Z / sidmohan
-
-- Decision: Pass review gate for this phase after `tests/plugin-smoke.test.ts` became non-mocked and validated real execution semantics.
-  Rationale: The review no longer has blocking findings and contract behavior is reproducible from a clean checkout.
-  Date/Author: 2026-02-16T18:05:00Z / sidmohan
-
-## Outcomes & Retrospective
-
-- Baseline was verified and stabilized before changes: tests and build passed.
-- Submission readiness work for `@openclaw/fogclaw` is complete in-code and test-verified with a real plugin execution-path smoke check.
-- Core entity detection behavior was intentionally unchanged; release-risk now centers on documentation and reviewer-facing reproducibility.
-- Acceptance evidence was reproduced on a clean checkout for the current verification set.
-- High-priority review finding `C-1` is mitigated in implementation by `tests/plugin-smoke.test.ts` using non-mocked `Scanner` execution.
-- Formal re-review completed (`PASS`) and gate criteria are no longer blocking.
-
-## Context and Orientation
-
-This repository’s source tree is small and focused: `src/` contains runtime plugin code, `tests/` contains unit coverage, and `docs/` contains planning and runbook artifacts.
-
-Key files a novice needs to know right away:
-
-- `src/index.ts` — plugin entrypoint. It registers hook and tools.
-- `src/scanner.ts` — orchestrates regex + GLiNER detection.
-- `src/redactor.ts` — implements token/mask/hash replacement.
-- `src/config.ts` — validates and defaults configuration.
-- `openclaw.plugin.json` — plugin manifest.
-- `package.json` — package metadata, dependencies, and `openclaw.extensions` pointer to `./dist/index.js`.
-- `README.md` — install and usage guidance.
-
-Repository naming context:
-- Branch `openclaw-plugin-submission` is where this `@openclaw` effort is taking place.
-- `main` in this repo currently points to a shorter baseline state where package naming and docs are not the focus of this iteration.
-
-## Milestones
-
-### Milestone 1 - Submission Contract Alignment
-
-By the end of this milestone, all metadata and publishing-facing naming for the `@openclaw/fogclaw` line should be internally consistent so maintainers do not have to infer intent. Expected changes are focused on docs and lockfile/package identity, not scanning logic. Verification should show a single package identity in plugin-facing docs and manifest assumptions.
-
-### Milestone 2 - Deterministic Smoke Proof Path
-
-By the end of this milestone, there is a reproducible command sequence for a reviewer to confirm plugin wiring without external services. This includes a way to execute plugin registration through a minimal mock OpenClaw API call path and assert both tool outputs and hook prepended context behavior.
-
-### Milestone 3 - PR Evidence and Submission Handback
-
-By the end of this milestone, the PR should include concise evidence artifacts and required docs that demonstrate command outputs, plus updates to domain docs if needed to capture any newly formalized operational constraints (security/reliability expectations around redaction and optional GLiNER fallback).
-
-## Plan of Work
-
-Start by making all plan deliverables explicit and low-risk.
-
-For Milestone 1, the work is to normalize package-facing identity around `@openclaw/fogclaw` for this branch and verify `openclaw.plugin.json` and exported plugin contract are already coherent. If any mismatch remains, only update naming and references; do not alter detection algorithms.
-
-For Milestone 2, define and document a deterministic test strategy for the plugin contract in tests (or a script plus test fixture), so reviewer behavior can be validated without downloading models. This strategy should validate all three behaviors: hook registration shape, scan tool output shape, and redact tool output shape.
-
-For Milestone 3, add a short evidence section in docs (README or dedicated file under docs) that lists the exact commands and expected outputs. Then update `docs/SECURITY.md` or `docs/RELIABILITY.md` only if this initiative established a new operating rule not already documented in those files.
-
-Throughout, keep `docs/PLANS.md` requirements in mind:
-
-- all milestones must be independently verifiable;
-- each `Progress` item must stay timestamped and stable;
-- include evidence snippets in `Artifacts and Notes`.
-
-## Concrete Steps
-
-From repo root:
-
-    npm test
-
-Expected:
-
-    ✓ tests/... (all passing, including plugin-smoke contract test)
-
-From repo root:
-
-    npm run build
-
-Expected:
-
-    Dist artifacts in `dist/` and no TypeScript errors.
-
-From repo root:
-
-    cat package.json | rg '"name":'
-    cat package-lock.json | rg '"name":'
-
-Expected:
-
-    Both should clearly reflect `@openclaw/fogclaw` for this branch.
-
-From repo root:
-
-    rg -n 'openclaw plugins install|fogclaw\.plugin\.json|export default fogclaw|register\(api\)' README.md openclaw.plugin.json src/index.ts docs
-
-Expected:
-
-    No conflicting publish/package identity references across the main files.
-
-From repo root:
-
-    npm pkg get openclaw
-
-Expected:
-
-    { "extensions": ["./dist/index.js"] }
-
-From repo root:
-
-    npm run build
-    node - <<'NODE'
-import plugin from './dist/index.js';
-console.log(typeof plugin?.register === 'function', plugin?.id, plugin?.name);
-NODE
-
-Expected:
-
-    true fogclaw FogClaw
-
-From repo root:
-
-    npm run test:plugin-smoke
-
-Expected:
-
-    test suite passes and validates hook + tool contract behavior using non-mocked OpenClaw API.
-
-## Validation and Acceptance
-
-Acceptance is behavior-based:
-
-- Build command is green and produces the expected output artifact entry points.
-- Package/manifest consistency for the `@openclaw/fogclaw` track is explicit and verified.
-- Plugin registration path is testable from a clean Node import and outputs known values in mock OpenClaw context.
-- `fogclaw_scan` and `fogclaw_redact` produce deterministic outputs in tests, including redaction replacement in at least one scenario.
-- Open questions remain none for release-critical mismatches on this branch.
-
-Acceptance checkpoints:
-
-- Run `npm test` and ensure no regressions.
-- Run `npm run build` and ensure no compile failure.
-- Run the smoke evidence sequence and attach command output in PR body.
-- Validate PR text includes explicit mention of `@openclaw/fogclaw` as scope.
-
-## Idempotence and Recovery
-
-Most edits are idempotent string replacements and test/doc additions, so repeating them should not alter behavior.
-
-If plugin-smoke test creation fails, run only that file and inspect fixture expectations first. If failures persist, remove the failing expectation and realign to the actual `OpenClaw` API contract surfaced by `src/index.ts` before re-running.
-
-If package-lock mismatch appears after `npm install`, prefer rerunning `npm install` and reviewing resulting root metadata changes before applying manual edits.
-
-If there is uncertainty during transition, preserve this plan and branch as the single source of truth and pause in this repo before PR handoff.
-
-## Artifacts and Notes
-
-Repository baseline evidence:
-
-    npm test
-    npm run build
-
-Expected output summary:
-
-    All tests pass and tsc compile succeeds.
-
-Captured evidence artifacts (commands + outputs):
-
-- Build/verification sequence:
-
-    npm run build
-    npm run test
-    npm run test:plugin-smoke
-    npm pkg get openclaw
-    node - <<'NODE'
-import plugin from './dist/index.js';
-console.log(typeof plugin?.register === 'function', plugin?.id, plugin?.name);
-NODE
-
-Observed output highlights:
-
-- `npm run build` succeeds.
-- `npm run test` reports 6 test files and 101 passing.
-- `npm run test:plugin-smoke` reports 3 passing tests.
-- `npm pkg get openclaw` returns `{ "extensions": ["./dist/index.js"] }`.
-- Plugin import check prints `true fogclaw FogClaw`.
-
-Planned and captured evidence artifacts:
-
-- `npm test` runs `98` existing tests plus the new plugin smoke test (`101` total), all passing.
-- `npm run build` succeeds with no TypeScript errors and emits `dist/index.js`.
-- `npm run test:plugin-smoke` passes with:
-  - `FogClaw OpenClaw plugin contract` hook registration validated
-  - scan tool output JSON shape validated
-  - redact tool output validation validated
-- `npm pkg get openclaw` returns `{"extensions":["./dist/index.js"]}`.
-- `node` smoke import check prints `true fogclaw FogClaw`.
-- Package identity mismatch resolved for branch target: `package.json`, `package-lock.json`, and README installation example now use `@openclaw/fogclaw`.
-
-
-## Interfaces and Dependencies
-
-Repository interfaces used by this initiative:
-
-- OpenClaw plugin export contract: default export with `{ id, name, register(api) }`.
-- `api.on("before_agent_start", handler)` for guardrail hook flow.
-- `api.registerTool({...})` for `fogclaw_scan` and `fogclaw_redact`.
-- `DEFAULT_CONFIG` and `loadConfig` from `src/config.js` for runtime defaults and validation.
-- `Scanner` + `redact` functions in `src/scanner.ts` and `src/redactor.ts` for deterministic entity handling.
-
-Third-party dependencies relevant to this plan:
-
-- `gliner` and `onnxruntime-node` remain production dependencies.
-- `vitest` is used for deterministic testing.
-- `typescript` ensures build and typing.
-
-## Pull Request
-
-- pr: https://github.com/DataFog/fogclaw/pull/1
-- branch: openclaw-plugin-submission
-- commit: 3deae344d41b103d3ee084619e6fb6b3e1bc1a82 (merge commit)
-- merged: 2026-02-17T01:53:23Z
-- ci:
-  - Docs Drift Gate: pass
-  - Docs Lint: pass
-
-## Review Findings
-
-### Correctness
-
-| ID | Priority | Location | Summary |
-|---|---|---|---|
-
-No active correctness findings.
-
-This section was left open during re-review because the previous mock-only finding (`C-1`) has now been remediated by `tests/plugin-smoke.test.ts` using a real `Scanner` execution path.
-
-**N/A items**: Migration safety (no migrations), data persistence correctness (no DB), concurrency ordering (no shared mutable state across request handlers in this change).
-
-### Architecture / Invariants
-
-| ID | Priority | Location | Summary |
-|---|---|---|---|
-| None | — | — | No architectural regressions identified in this review window. |
-
-No findings.
-
-**N/A items**: Dependency management (no new runtime dependency), API boundaries (no schema changes), migration path (no migrations), observability hooks (no new production observability path).
-
-### Security
-
-| ID | Priority | Location | Summary |
-|---|---|---|---|
-| None | — | — | No new security-sensitive input paths or secret-handling changes were introduced. |
-
-No findings.
-
-**N/A items**: Authentication/authorization (plugin runtime unchanged), command execution, HTML rendering, SQL/query surfaces (not present in this change).
-
-### Data Integrity / Privacy
-
-| ID | Priority | Location | Summary |
-|---|---|---|---|
-| None | — | — | No direct data persistence, migration, or data model changes in this initiative. |
-
-No findings.
-
-**N/A items**: Transactionality, soft deletes, retention policy, exports (no persisted data or new persistence surface introduced).
-
-### Simplicity
-
-| ID | Priority | Location | Summary |
-|---|---|---|---|
-| None | — | — | The change set is narrowly scoped and follows existing TypeScript patterns. |
-
-No findings.
-
-**N/A items**: Speculative abstractions (no speculative architecture added), circular abstractions (none), one-off style divergence (minimal and scoped to plugin smoke/README evidence).
-
-### Summary
-
-0 critical, 0 high, 0 medium, 0 low after re-review of this batch.
-
-### Gate Decision
-
-**PASS** — plugin contract behavior is now covered by a non-mocked execution-level smoke test (`tests/plugin-smoke.test.ts`) that validates real registration, scan, redact, and hook outcomes.
-
-Medium/low findings to tech debt tracker: none.
-
-## Verify/Release Decision
-
-- decision: GO
-- date: 2026-02-16T18:07:00Z
-- open findings by priority (if any): none
-- evidence: 
-  - `npm test`
-  - `npm run test:plugin-smoke`
-  - `npm run build`
-  - `npm pkg get openclaw`
-  - node import smoke check (`true fogclaw FogClaw`)
-  - `gh pr checks` (all current checks green)
-- rollback: restore commit `6a76311` and rerun evidence sequence
-- post-release checks: run `npm test`, `npm run test:plugin-smoke`, and rerun `gh pr checks` on `main` after merge
-- owner: sidmohan
-
-## Revision Notes
-
-- 2026-02-16T17:50:00Z: Aligned planning scope to `@openclaw/fogclaw` explicitly based on user instruction; marked `@datafog/fogclaw` as historical/out-of-scope for this iteration.
-- 2026-02-16T17:50:15Z: Replaced incomplete/partial plan draft with a complete PLANS.md-compliant structure, including all required sections and milestone sequence.
-- 2026-02-16T17:53:20Z: Completed end-of-`he-plan` domain-doc population (`docs/SECURITY.md`, `docs/RELIABILITY.md`) with repository-specific submission-safety rules and recovery/rollback guidance.
-- 2026-02-16T17:55:50Z: Executed he-plan follow-through by adding package identity + lockfile alignment for `@openclaw/fogclaw`, adding `tests/plugin-smoke.test.ts` for hook/tool contract verification, and documenting submission-ready evidence commands in `README.md`.
-- 2026-02-16T17:56:20Z: Completed he-implement handoff actions and baseline evidence checks in preparation for review.
-- 2026-02-16T17:59:00Z: Ran `he-review`, recorded blocking finding `C-1` and returned to implementation for remediation.
-- 2026-02-16T18:00:10Z: Addressed `C-1` by rewriting plugin contract smoke test to non-mocked execution and updated gate-related plan sections.
-- 2026-02-16T18:05:00Z: Re-ran full evidence sequence (`npm test`, `npm run build`, `npm run test:plugin-smoke`) and cleared review block in plan.
-- 2026-02-16T18:05:00Z: Follow-up `he-review` pass completed with PASS; no open findings.
-- 2026-02-16T18:07:00Z: Completed `he-github` PR open + `gh pr checks` pass; transitioned to `he-verify-release` with no open findings.
-- 2026-02-17T01:53:23Z: PR merged to `main` on DataFog/fogclaw (`#1`) after required checks remained green.