Fix publication blockers for v0.1.0 release candidate

[darko-mijic]

Summary

This PR resolves the remaining pre-publication blockers for @libar-dev/agent-harness-kit v0.1.0 release candidate. It fixes stale documentation links and wording, normalizes npm package metadata, moves build-time tooling out of production dependencies, hardens image-content-block handling with a shared helper and regression tests, and replaces the fragile upstream-doc mirror workflow with direct markdown sync from code.claude.com.

It also removes the ephemeral planning context file that was added during the API parity pass; planning artifacts should not be committed to the public repo.

Detailed Changes

Documentation Fixes

• CONTRIBUTING.md: Fixed broken architecture overview link to point to docs/README.md.
• CHANGELOG.md: Expanded [0.1.0] release notes with ### Added (image content block support) and additional ### Changed entries (bin paths, repository URL, publishConfig.access).
• CHANGELOG.md: Removed stale [1.0.0] release link pointing to the old claude-code-hooks repo.
• SECURITY.md: Softened pre-1.0 maturity wording to "release candidate" and fixed grammar.

Package Metadata Normalization

• Moved tsx from dependencies to devDependencies (it is only used for local script execution; published CLIs use #!/usr/bin/env node shebangs).
• Regenerated pnpm-lock.yaml importer metadata to match the tsx move.
• Added top-level "sideEffects": false for improved tree-shaking by consumers.
• Existing normalized fields remain unchanged: bin paths without ./, repository.url with git+ prefix.

Image Content Block Hardening

• Extracted duplicated imagePlaceholder logic into src/processing/image-placeholder.ts.
• New helper imports isRecord from src/utils/index.js and explicitly rejects arrays, returning the generic [Image] placeholder.
• Updated src/processing/denoiser.ts and src/processing/block-decomposition.ts to import the shared helper.
• Added regression tests covering image sources that are arrays, null, or primitives for both denoiseSession and extractBlocks paths.
• No base64 image data is leaked — only safe media_type metadata is used in placeholders.

Upstream Docs Sync Automation

• Added scripts/sync-upstream-docs.mjs and pnpm run docs:sync-upstream to fetch canonical markdown directly from https://code.claude.com/docs/en/*.md.
• Updated docs/upstream/README.md to document the new source of truth and the refresh command.
• Refreshed the mirrored upstream docs for hooks, settings, CLI, and headless/programmatic usage from the live .md endpoints.
• Eliminated the manual copy-paste path that had already produced malformed mirrors (headless.md duplicated CLI content and hooks-reference.md contained mixed page sections).

Code Cleanup + Slop Removal

• Removed obvious comments, dead code, and over-defensive guards across source, tests, and docs.
• Deleted the .omo/ work-tracking directory and docs/internal/prometheus-implementation-context.md.
• Added a ## Public Repository Hygiene guardrail to AGENTS.md so future agents know ephemeral planning artifacts must not be merged.
• Tightened docs wording while preserving commands, examples, and API facts.
• Locked new behavior with regression tests for Setup/MessageDisplay and the expanded output builder methods.
• All quality gates green: 1201 tests, type-check, lint, build.

Why This Is Needed

1. Broken contributor link: The architecture overview link in CONTRIBUTING.md pointed to a non-existent file.
2. Missing sideEffects: false: Consumers cannot safely tree-shake the package without this explicit marker.
3. tsx in production dependencies: Adds unnecessary install weight and implies runtime dependency on a TypeScript executor that is not used by published artifacts.
4. Duplicated image placeholder logic: Two divergent implementations existed (denoiser.ts accepted arrays; block-decomposition.ts rejected them). The shared helper normalizes behavior and adds regression coverage for malformed image sources.
5. Stale/misleading docs: SECURITY wording was too strong for a pre-1.0 package, and the CHANGELOG contained a dead link to the old repo.
6. Untrustworthy upstream mirrors: Manual copy-paste had already introduced malformed docs into docs/upstream/, which made API-gap assessment noisy and easy to get wrong.
7. Planning artifacts in public repo: The ephemeral context file and .omo/ directory were useful during implementation but must not be shipped in a public release.

Comment Consistency Cleanup

After the initial cleanup pass, a plan was created to fix the inconsistent comment state it left behind. This branch now includes the final wave of that cleanup.

What changed

• Restored and expanded public API JSDoc in src/utils/index.ts for exported helpers:
  • toError — normalize an unknown value to an Error.
  • isRecord — type guard for non-null object records.
  • isProtectedFile — pattern-based protection check, with a security note that it is not a filesystem access-control boundary.
  • validateRequiredFields — required-field presence check, now with @returns void.
  • validateFilePath — path-traversal guard, now with @returns void.
  • sanitizeCommand — shell-metacharacter stripping, with an explicit note that it is not a full shell-injection sanitizer.
• Removed remaining banned filler words from source comments:
  • src/processing/tail.ts — "incremental" → "appended-block"; "automatically advanced" → "advances".
  • src/processing/types.ts — "incremental ingestion" → "ingestion of growing session files".
  • src/processing/discovery.ts — "supports filtering" → "filters".
  • src/lifecycle/stop-handler.ts — "TODO comments" → "TODO markers".
  • src/pre-tool-use/eslint-disable-blocker.ts — removed two "automatically" filler instances.

Verification

• Banned-phrase grep across src/ and tests/ returns only documented opt-outs:
  • src/cli/export-sessions.ts:219 — runtime CLI message string "incremental export".
  • src/processing/ordering.ts:7 — false-positive substring "re-exported from".
  • tests/tail.test.ts:1074,1390 — executable it() description strings containing "incremental".
• Final Verification Wave approvals:
  • F1. Plan Compliance Audit — APPROVE
  • F2. Code Quality Review — APPROVE
  • F3. Real Manual QA — APPROVE
  • F4. Scope Fidelity Check — APPROVE

Testing Performed

• pnpm run type-check — passes cleanly.
• pnpm run lint — passes.
• pnpm run lint:ci — passes.
• pnpm run test:run — 1201 tests passing, 0 failures.
• pnpm run build — produces correct dist/ structure.
• npm publish --dry-run --access public — passes.
• npm pack — produces clean tarball with required docs, dist/, and package.json; no src/, .DS_Store, or .omo/ leaks.
• pnpm run docs:sync-upstream — refreshes all mirrored upstream docs from canonical .md endpoints.
• pnpm run docs:sync-upstream -- settings — targeted sync works for a single mirrored page.
• pnpm run test:run -- tests/docs-round-trip.test.ts — passes with the refreshed mirrors.

Verification Checklist

• CONTRIBUTING.md architecture link points to existing docs/README.md
• CHANGELOG.md [0.1.0] section has expanded Added/Changed release notes
• CHANGELOG.md no longer contains stale old-repo release link
• SECURITY.md uses grammatically correct "release candidate" wording
• package.json contains "sideEffects": false
• tsx moved to devDependencies; lockfile regenerated
• pnpm install --frozen-lockfile succeeds
• Shared image-placeholder.ts helper exists and is used by both processing callers
• Image block regression tests cover array, null, and primitive sources
• No base64 image data leaked in placeholders
• Full test suite passes: 1201 tests
• npm publish --dry-run passes
• npm pack contents verified clean
• pnpm run docs:sync-upstream refreshes upstream mirrors from code.claude.com markdown endpoints
• docs/upstream/headless.md is no longer a duplicate of CLI reference content
• docs/upstream/hooks-reference.md is a clean hooks-reference mirror again
• tests/docs-round-trip.test.ts now uses content-based skip classification instead of brittle block indices
• Ephemeral planning artifacts removed (.omo/, docs/internal/prometheus-implementation-context.md)
• AGENTS.md includes Public Repository Hygiene guardrail
• Public API JSDoc restored and expanded in src/utils/index.ts
• Banned filler words removed from source comments

Breaking Changes

None. All changes are additive, metadata normalization, automation, or internal refactoring.

Claude Code Hook API Parity

This branch also closes the gap between the library and the current upstream Claude Code hook API surface (source of truth: docs/upstream/hooks-reference.md).

Added hook events

• Setup — modeled as a full hook event with SetupInput/SetupOutput, Zod schemas, type guards, validators, HookOutputBuilder.setupContext(), and a reference lifecycle handler (src/lifecycle/setup.ts).
• MessageDisplay — modeled with MessageDisplayInput/MessageDisplayOutput, UUID-aware schemas, type guards, validators, HookOutputBuilder.messageDisplayContent(), and a reference lifecycle handler (src/lifecycle/message-display.ts).

Expanded existing events

• SessionStart:
  • Input: model is now optional; added session_title.
  • Output: hookSpecificOutput now supports additionalContext, initialUserMessage, sessionTitle, watchPaths, and reloadSkills.
• Notification: enum widened to all 6 upstream notification types.
• StopFailure: enum widened to all 10 upstream stop-failure reasons.
• PostToolUse / PostToolUseFailure: added optional duration_ms to both inputs.
• PostToolUse output: added updatedToolOutput and widened updatedMCPToolOutput to unknown.
• Common base fields: effort on BaseHookInput, terminalSequence on BaseHookOutput.
• CommandHookHandler: added optional args?: string[] for the exec-form command surface.

Reference handlers and tooling

• New pnpm run hook:test:setup and pnpm run hook:test:message-display scripts.
• Lifecycle smoke tests for Setup and MessageDisplay handlers.
• Updated src/lifecycle/session-start.ts to tolerate a missing model and src/lifecycle/notification-handler.ts to classify new notification types.

Docs and metadata

• README/CLAUDE.md/package.json/docs references updated from 28 to 30 hook events.
• CHANGELOG.md entry added for the API parity changes.
• New test factories createSetupInput and createMessageDisplayInput in tests/test-utils.ts.

Verification

• pnpm run test:run — 1201 tests passing, 0 failures.
• pnpm run check — type-check + lint pass.
• pnpm run hook:test:setup — exits 0.
• pnpm run hook:test:message-display — exits 0.
• CLAUDE_PROJECT_DIR=/Users/darkomijic/dev-projects/claude-code-hooks pnpm run hook:test:session — exits 0.
• Scope enforcement checks pass: no new .passthrough(), no new any, package.json version unchanged, docs/upstream/ untouched, no public exports removed.

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.