Verify Package Integrity

[rucka]

Resolution

Delivered by PR #138 (merged). Board: Done.

feat: KB package integrity verification.

Story Statement

As a developer installing KB packages from external sources (ZIP files, URLs)
I want to verify package integrity before installation using pair kb verify <package> and automatic verification during pair install
So that I can trust the KB content has not been corrupted or tampered with, preventing broken installations and ensuring security

Where: Command-line interface (pair kb verify standalone command + automatic hook in pair install)

Epic Context

Parent Epic: #65 Enhanced CLI Packaging & Distribution
Status: Done
Priority: P1 (Should-Have)

Status Workflow

• Refined: Story is detailed, estimated, and ready for development ✅
• In Progress: Story is actively being developed
• Done: Story delivered and accepted ✅

Acceptance Criteria

Functional Requirements

Given-When-Then Format:

1. Given a valid KB package ZIP created by pair kb package
   When user runs pair kb verify my-kb.zip
   Then system outputs a verification report showing: checksum status (PASS), structure validation (PASS), manifest validation (PASS), overall result (PASS), and exits with code 0

2. Given a KB package ZIP with corrupted content (file bytes modified after packaging)
   When user runs pair kb verify corrupted-kb.zip
   Then system outputs a verification report showing checksum status (FAIL) with expected vs actual SHA-256 hashes, overall result (FAIL), and exits with code 1

3. Given a ZIP file missing required .pair/ directory structure
   When user runs pair kb verify incomplete-kb.zip
   Then system outputs a verification report showing structure validation (FAIL) listing missing required directories, overall result (FAIL), and exits with code 1

4. Given a ZIP file with missing or malformed manifest.json
   When user runs pair kb verify no-manifest-kb.zip
   Then system outputs a verification report showing manifest validation (FAIL) with specific error (missing file or invalid JSON or missing required fields), overall result (FAIL), and exits with code 1

5. Given a valid KB package ZIP and pair install --source ./my-kb.zip
   When user runs the install command
   Then system automatically verifies the package before extraction, displays brief verification status ("Verification passed"), and proceeds with installation

6. Given an invalid KB package ZIP and pair install --source ./bad-kb.zip
   When user runs the install command
   Then system automatically verifies the package, displays verification failure details, aborts installation with error message "Package verification failed. Use --skip-verify to bypass.", and exits with code 1

7. Given an invalid KB package ZIP
   When user runs pair install --source ./bad-kb.zip --skip-verify
   Then system skips verification entirely, displays warning "Skipping package verification (--skip-verify)", and proceeds with installation normally

8. Given user wants machine-readable output
   When user runs pair kb verify my-kb.zip --json
   Then system outputs the verification report as a JSON object with fields: { package, timestamp, checks: { checksum, structure, manifest }, overall } and exits with appropriate code

9. Given a file path that does not exist
   When user runs pair kb verify nonexistent.zip
   Then system outputs error "File not found: nonexistent.zip" and exits with code 1

10. Given a file that is not a valid ZIP archive
    When user runs pair kb verify not-a-zip.txt
    Then system outputs error "Invalid ZIP archive: not-a-zip.txt" and exits with code 1

Business Rules

• Checksum algorithm: SHA-256 (matches existing calculateSHA256 in @pair/content-ops)
• Checksum storage: SHA-256 hash of the packaged content stored in manifest.json field contentChecksum during pair kb package
• Verification order: checksum first, then structure, then manifest fields (fail-fast on checksum)
• Default behavior during install: verification is ON; opt-out with --skip-verify
• Performance target: verification completes in <5 seconds for packages up to 100MB
• Exit codes: 0 = all checks pass, 1 = any check fails or error
• Manifest required fields: name, version, created_at, registries (matching ManifestMetadata interface)
• Structure required paths: at least one registry source directory must exist in the ZIP (as declared in manifest.json registries array)
• No caching: verification runs fresh each time (fast enough without cache)

Edge Cases and Error Handling

• Corrupted ZIP file: adm-zip throws on extraction attempt; catch and report "Invalid or corrupted ZIP archive"
• Empty ZIP file: report structure validation failure "ZIP archive is empty"
• Very large packages (>500MB): proceed normally; SHA-256 streaming handles large files via createReadStream
• Manifest with extra fields: ignore unknown fields, validate only required ones
• Manifest registries references missing directories: report each missing directory in structure check
• Permission denied on ZIP file: report "Cannot read file: permission denied"
• Concurrent verification: no shared state; safe to run multiple verifications simultaneously
• Symlinks in ZIP: skip during structure check (consistent with pair kb package behavior)

Definition of Done Checklist

Development Completion

• pair kb verify <package> command implemented in apps/pair-cli/src/commands/kb-verify/
• --json flag outputs machine-readable verification report
• --skip-verify flag added to pair install command parser
• Automatic verification integrated into installKBFromLocalZip in kb-installer.ts
• pair kb package updated to compute and embed contentChecksum in manifest.json
• All verification checks implemented: checksum, structure, manifest
• Error handling covers all edge cases listed above

Quality Assurance

• Unit tests for each verification check (checksum, structure, manifest) using InMemoryFileSystemService
• Unit tests for --json output format
• Unit tests for --skip-verify flag in install parser
• Integration test: package -> verify -> install roundtrip
• Integration test: corrupted package detection
• All existing tests pass (pnpm --filter @pair/pair-cli test)
• Quality gate passes (pnpm quality-gate)

Deployment and Release

• Command registered in commandRegistry in commands/index.ts
• Command metadata includes help text and examples
• No breaking changes to existing pair install behavior (verify is additive)
• CLI documentation updated (commands.md, cli-contracts.md, help-examples.md, pair-cli/README.md, 02-cli-workflows.md, root README.md)

Code Review and Delivery

• Pull request created: PR #138
• Code reviewed and approved
• PR merged to main (squash merge 001232e)
• Story closed

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: 3
Confidence Level: High
Sizing Justification: Most cryptographic and ZIP infrastructure already exists in @pair/content-ops (calculateSHA256, validateChecksum, extractZip, adm-zip). The manifest metadata interface (ManifestMetadata) is defined. The command pattern (parser/handler/metadata) is well-established with 6 existing commands to follow. Primary new work is: (1) wiring verification checks into a new command, (2) adding checksum to package creation, (3) integrating verification hook into install flow. No spikes needed.

Sprint Capacity Validation

Sprint Fit Assessment: Fits within a single sprint
Development Time Estimate: 2-3 days for a developer familiar with the codebase
Testing Time Estimate: Included in development estimate
Total Effort Assessment: Fits within sprint capacity: Yes

Story Splitting Recommendations

No splitting needed. The 3 logical units (standalone command, install integration, package checksum) are tightly coupled and individually non-valuable.

Dependencies and Coordination

Story Dependencies

• Package KB Content #73 (Package KB Content): DONE. Provides the packaging command that creates ZIPs with manifest.json. This story extends it with contentChecksum.
• Validate KB Content #74 (Validate KB Content): DONE. Provides pair kb-validate for structure validation. This story adds ZIP-level verification as a distinct concern.
• CLI Default KB Installation #78 (CLI Default KB Installation): DONE. Provides default install flow.
• Install from URL or Local Path #79 (Install from URL, ZIP, or Directory): DONE. Provides installKBFromLocalZip where auto-verification hooks in.

Team Coordination

• Single developer can implement end-to-end
• No cross-team dependencies

External Dependencies

• adm-zip (already in dependencies for both @pair/content-ops and @pair/pair-cli)
• Node.js crypto module (built-in, already used by integrity-validator.ts)

Validation and Testing Strategy

Acceptance Testing Approach

• Checksum verification: Create a valid package, modify a byte in the ZIP, verify detection
• Structure verification: Create ZIPs with missing directories, verify each is detected
• Manifest verification: Create ZIPs with missing/malformed manifest, verify detection
• Install integration: Run pair install --source with both valid and invalid packages
• JSON output: Validate output matches expected schema
• Skip-verify: Confirm installation proceeds despite invalid package when flag is set

User Validation

• Demo: verify a valid package (PASS), then corrupt it and verify again (FAIL)
• Demo: attempt install with corrupted package (blocked), then with --skip-verify (proceeds)

Notes and Additional Context

Refinement Session Insights

• Verification is intentionally separate from pair kb-validate (which validates an installed/extracted KB directory). pair kb verify operates on ZIP files pre-installation.
• The contentChecksum in manifest.json is a SHA-256 hash computed over all non-manifest files in the ZIP during packaging. This enables detecting tampering even without an external .sha256 file.
• The existing checksumManager.validateFileWithRemoteChecksum in kb-installer.ts handles remote download checksums (.sha256 sidecar files). This story adds local package verification which is complementary.

Team Concerns

• None identified. Well-established patterns and libraries.

Future Considerations

• Digital signatures: Future enhancement could add GPG/PGP signature verification for organizational trust chains (explicitly out of scope per epic Simple KB Distribution & Installation #65).
• Content-level validation: Post-extraction content validation (link integrity, completeness) is covered by Validate KB Content #74 pair kb-validate, not this story.
• Remote URL verification: The existing checksumManager handles .sha256 sidecar files for remote downloads. This story's verification could be extended to remote sources in a future story.

Technical Analysis

Implementation Approach

Technical Strategy: Add a new kb-verify command following the established command pattern (parser + handler + metadata + index). Extend pair kb package to embed a contentChecksum field in manifest.json. Hook verification into installKBFromLocalZip with opt-out flag.

Key Components:

1. apps/pair-cli/src/commands/kb-verify/ (new command directory)

   • parser.ts: Parse <package> positional arg + --json flag
   • handler.ts: Orchestrate verification checks, format output
   • metadata.ts: Command help text, examples, options
   • index.ts: Re-export for command registry

2. Verification engine (in handler or extracted utility)

   • verifyChecksum(zipPath, manifest): Compare contentChecksum from manifest against computed SHA-256 of ZIP content files
   • verifyStructure(zipEntries, manifest): Check that registry directories declared in manifest.registries exist in the ZIP
   • verifyManifest(manifestContent): Validate required fields exist and are valid types

3. Package checksum embedding (modify existing)

   • Extend createPackageZip in apps/pair-cli/src/commands/package/zip-creator.ts: After copying registry sources to temp dir, compute SHA-256 over all files, add contentChecksum to manifest before writing

4. Install integration (modify existing)

   • Add --skip-verify to InstallCommandConfig discriminated union in install/parser.ts
   • Add verification step in installKBFromLocalZip in kb-manager/kb-installer.ts before extractZip/finalizeZipInstall

Data Flow (standalone pair kb verify):

1. Parse positional arg (ZIP path), validate file exists
2. Open ZIP with adm-zip, read manifest.json entry
3. Parse manifest, validate required fields
4. Compute SHA-256 of all non-manifest entries in ZIP
5. Compare computed hash with manifest.contentChecksum
6. Check registry directories from manifest.registries exist as ZIP entries
7. Format and output verification report (human-readable or JSON)

Technical Requirements

• Reuse calculateSHA256 from @pair/content-ops/file-system/integrity-validator for checksum computation
• Reuse adm-zip (already a dependency) for reading ZIP entries without full extraction
• Reuse ManifestMetadata interface from apps/pair-cli/src/commands/package/metadata.ts, extending it with optional contentChecksum: string
• Follow command pattern: parser returns typed config, handler receives config + FileSystemService
• JSON output schema:

  {
    "package": "my-kb.zip",
    "timestamp": "2026-02-14T10:00:00Z",
    "checks": {
      "checksum": { "status": "PASS|FAIL", "expected": "abc...", "actual": "abc...", "algorithm": "SHA-256" },
      "structure": { "status": "PASS|FAIL", "requiredPaths": ["knowledge", "skills"], "missingPaths": [] },
      "manifest": { "status": "PASS|FAIL", "errors": [] }
    },
    "overall": "PASS|FAIL"
  }

Technical Risks and Mitigation

Risk	Impact	Probability	Mitigation
adm-zip fails on corrupted ZIP before we can read manifest	Low	Medium	Wrap in try/catch, report "Invalid or corrupted ZIP archive"
Computing SHA-256 over all ZIP entries is slow for large packages	Low	Low	Use streaming hash via createHash('sha256') + iterating entries; <5s target
Modifying ManifestMetadata breaks existing package consumers	Medium	Low	contentChecksum is optional field; existing consumers ignore unknown fields
--skip-verify in install could confuse users unfamiliar with it	Low	Low	Only shown in --help; not prompted during normal flow

Spike Requirements

None. All technologies and patterns are already proven in the codebase:

• SHA-256: packages/content-ops/src/file-system/integrity-validator.ts
• ZIP reading: adm-zip used in file-system-service.ts and archive-operations.ts
• Command pattern: 6 existing commands in apps/pair-cli/src/commands/
• Manifest handling: apps/pair-cli/src/commands/package/metadata.ts

Task Breakdown

• T-1: Embed contentChecksum in manifest during packaging
• T-2: Create kb-verify command with verification engine
• T-3: Integrate auto-verification into install flow
• T-4: Update CLI documentation for kb-verify command and --skip-verify flag

Dependency Graph

T-1 ── T-2 ── T-3 ── T-4

AC Coverage

AC	Description	Tasks
AC-1 (valid → PASS)	Valid package verification passes	T-1, T-2
AC-2 (corrupted → checksum FAIL)	Corrupted content detected	T-1, T-2
AC-3 (missing structure → FAIL)	Missing directories detected	T-2
AC-4 (malformed manifest → FAIL)	Invalid manifest detected	T-2
AC-5 (install auto-verify → proceed)	Auto-verify on install	T-3
AC-6 (install auto-verify → abort)	Abort install on failure	T-3
AC-7 (--skip-verify → bypass)	Skip verification flag	T-3
AC-8 (--json output)	JSON verification report	T-2
AC-9 (nonexistent file → error)	File not found error	T-2
AC-10 (non-ZIP → error)	Invalid archive error	T-2

---

T-1: Embed contentChecksum in manifest during packaging

Priority: P0 | Estimated Hours: 2h | Bounded Context: Knowledge Base Management

Summary: Extend pair kb package to compute SHA-256 over all non-manifest content files in the temp directory, then embed the hash as contentChecksum in manifest.json before creating the ZIP.

Type: Feature Implementation

Description: Currently createPackageZip writes manifest.json first, then copies registry sources, then zips everything. The checksum must be computed after all content files are copied but before the manifest is finalized. This requires reordering: (1) copy registry sources to temp, (2) compute SHA-256 over all temp files, (3) write manifest with contentChecksum, (4) create ZIP. The ManifestMetadata interface gains an optional contentChecksum field — optional so existing consumers don't break.

Acceptance Criteria:

• Primary deliverable: manifest.json inside packaged ZIPs contains contentChecksum field with valid SHA-256 hex string
• Quality standard: Unit tests verify checksum is present and deterministic (same content → same hash)
• Integration requirement: Existing pair kb package behavior unchanged except for added field
• Verification method: Package a KB, extract manifest.json, confirm contentChecksum matches manual SHA-256 computation

Technical Requirements:

• Functionality: Compute SHA-256 over all files in temp dir (excluding manifest.json itself), store as hex string
• Performance: <1s overhead for typical KB packages (<50MB)
• Security: SHA-256 cryptographic hash prevents tampering
• Compatibility: contentChecksum is optional — old consumers ignore it

Implementation Approach:

• Technical Design: Reorder createPackageZip to copy content first, then compute hash, then write manifest
• Bounded Context & Modules: Knowledge Base Management — packaging subsystem
• Files to Modify/Create:
  • apps/pair-cli/src/commands/package/metadata.ts — Add optional contentChecksum: string to ManifestMetadata
  • apps/pair-cli/src/commands/package/zip-creator.ts — Reorder to compute hash before manifest write, add computeContentChecksum helper
  • apps/pair-cli/src/commands/package/zip-creator.test.ts — Tests for checksum embedding

Dependencies:

• Technical: calculateSHA256 from @pair/content-ops, createHash from Node.js crypto
• Tasks: None (first in chain)

Implementation Steps:

1. Add contentChecksum?: string to ManifestMetadata interface in metadata.ts
2. Extract content-copy logic in createPackageZip to run before manifest write
3. Add computeContentChecksum(tempDir, fsService) that walks all files in temp dir, concatenates their SHA-256 hashes in sorted order, and produces a final hash
4. Pass computed checksum into manifest object before calling writeManifest
5. Write unit tests: verify checksum present, verify deterministic, verify existing packaging still works

Testing Strategy:

• Unit Tests: Test computeContentChecksum produces consistent hash; test ManifestMetadata with checksum field; test full createPackageZip includes checksum in manifest
• Integration Tests: Package → extract → parse manifest → verify contentChecksum field exists and is 64-char hex
• Manual Testing: Run pair package, unzip output, inspect manifest.json

Notes: The hash is computed over content files sorted by path to ensure deterministic ordering regardless of filesystem traversal order.

---

T-2: Create kb-verify command with verification engine

Priority: P0 | Estimated Hours: 6h | Bounded Context: Knowledge Base Management

Summary: Create the standalone pair kb-verify <package> command that performs checksum, structure, and manifest verification on a KB package ZIP, with human-readable and --json output modes.

Type: Feature Implementation

Description: New command following the established parser/handler/metadata/index pattern. The handler opens the ZIP with adm-zip, extracts and validates manifest.json, computes SHA-256 over non-manifest entries to compare with contentChecksum, and verifies that registry directories declared in manifest.registries exist as ZIP entries. Output is a verification report (human-readable by default, JSON with --json flag). Exits 0 on all-pass, 1 on any failure.

Acceptance Criteria:

• Primary deliverable: pair kb-verify command registered and functional with checksum/structure/manifest checks
• Quality standard: Full unit test coverage for each check; edge cases (corrupted ZIP, empty ZIP, missing manifest, non-ZIP file, nonexistent path) all handled
• Integration requirement: Registered in commandRegistry in commands/index.ts; CommandConfig union extended
• Verification method: Run against valid package (PASS), corrupted package (FAIL checksum), incomplete package (FAIL structure), no-manifest package (FAIL manifest)

Technical Requirements:

• Functionality: 3 verification checks (checksum, structure, manifest) with fail-fast on checksum; --json flag for machine-readable output
• Performance: <5s for packages up to 100MB
• Security: SHA-256 verification detects content tampering
• Compatibility: New command, no breaking changes

Implementation Approach:

• Technical Design: Parser extracts <package> positional + --json flag. Handler orchestrates 3 check functions and formats output. Each check returns { status: 'PASS'|'FAIL', details }.
• Bounded Context & Modules: Knowledge Base Management — verification subsystem
• Files to Modify/Create:
  • apps/pair-cli/src/commands/kb-verify/parser.ts — Parse <package> positional + --json flag → KbVerifyCommandConfig
  • apps/pair-cli/src/commands/kb-verify/handler.ts — Orchestrate checks, format output
  • apps/pair-cli/src/commands/kb-verify/metadata.ts — Command help, examples, options
  • apps/pair-cli/src/commands/kb-verify/index.ts — Re-exports
  • apps/pair-cli/src/commands/kb-verify/checks/checksum-check.ts — SHA-256 verification against contentChecksum
  • apps/pair-cli/src/commands/kb-verify/checks/structure-check.ts — Verify registry dirs exist in ZIP
  • apps/pair-cli/src/commands/kb-verify/checks/manifest-check.ts — Validate manifest required fields
  • apps/pair-cli/src/commands/kb-verify/report-formatter.ts — Human-readable + JSON formatters
  • apps/pair-cli/src/commands/index.ts — Register kb-verify in commandRegistry and CommandConfig union
  • apps/pair-cli/src/commands/kb-verify/*.test.ts — Unit tests

Dependencies:

• Technical: adm-zip, calculateSHA256 from @pair/content-ops, ManifestMetadata from package/metadata
• Tasks: T-1 (needs contentChecksum in manifest for checksum verification to be meaningful)

Implementation Steps:

1. Create apps/pair-cli/src/commands/kb-verify/ directory
2. Implement parser.ts with KbVerifyCommandConfig interface and parseKbVerifyCommand function
3. Implement metadata.ts with command help, examples, and options
4. Implement checks/manifest-check.ts — extract manifest.json from ZIP, validate required fields (name, version, created_at, registries)
5. Implement checks/structure-check.ts — verify each registries entry has corresponding directory in ZIP entries
6. Implement checks/checksum-check.ts — compute SHA-256 over non-manifest ZIP entries, compare with manifest.contentChecksum
7. Implement report-formatter.ts — format check results as human-readable table or JSON
8. Implement handler.ts — orchestrate: validate file exists + is ZIP, run checks in order (checksum → structure → manifest), format output, set exit code
9. Create index.ts re-exports
10. Register in commands/index.ts — add to imports, CommandConfig union, and commandRegistry
11. Write unit tests for parser, each check, report formatter, and handler

Testing Strategy:

• Unit Tests: Parser option parsing; each check function (PASS and FAIL cases); report formatter (human + JSON); handler integration with mock ZIP data using InMemoryFileSystemService
• Integration Tests: End-to-end: create valid ZIP → verify (PASS); corrupt ZIP → verify (FAIL checksum); remove dir from ZIP → verify (FAIL structure); remove manifest field → verify (FAIL manifest)
• Manual Testing: Run pair kb-verify valid.zip, pair kb-verify valid.zip --json, pair kb-verify bad.zip

Notes: adm-zip can read ZIP entries without extracting to disk — use getEntries() to inspect structure and readAsText('manifest.json') for manifest. For checksum, iterate entries and hash content buffers.

---

T-3: Integrate auto-verification into install flow

Priority: P0 | Estimated Hours: 3h | Bounded Context: Knowledge Base Management

Summary: Add --skip-verify flag to the install command parser and hook automatic package verification into installKBFromLocalZip (and resolveLocalDataset for ZIP paths) so that local ZIP installations are verified by default before extraction.

Type: Feature Implementation

Description: When pair install --source ./my-kb.zip is invoked, the system should automatically run the same verification checks from T-2 before extracting the ZIP. If verification fails, abort with a clear message suggesting --skip-verify. The --skip-verify flag bypasses verification with a warning. This hooks into installKBFromLocalZip in kb-installer.ts and the install parser in install/parser.ts.

Acceptance Criteria:

• Primary deliverable: pair install --source ./local.zip auto-verifies before extraction; --skip-verify bypasses
• Quality standard: Unit tests for parser flag, integration test for verify-then-install and skip-verify flows
• Integration requirement: No change to pair install default behavior (no source = no verification); verification only on local ZIP sources
• Verification method: Install valid ZIP (proceeds), install invalid ZIP (aborts with message), install invalid ZIP with --skip-verify (proceeds with warning)

Technical Requirements:

• Functionality: Auto-verification on local ZIP install; --skip-verify opt-out flag; clear error message on failure
• Performance: Adds <5s to install for packages up to 100MB
• Security: Prevents installing tampered/corrupted packages by default
• Compatibility: --skip-verify provides escape hatch; no breaking changes to existing install behavior

Implementation Approach:

• Technical Design: Add skipVerify?: boolean to all InstallCommandConfig variants. In installKBFromLocalZip, call verification checks before performExtractForZip. If verification fails and skipVerify is false, throw with actionable message. Pass skipVerify through resolveLocalDataset → installKBFromLocalZip.
• Bounded Context & Modules: Knowledge Base Management — install + verification integration
• Files to Modify/Create:
  • apps/pair-cli/src/commands/install/parser.ts — Add --skip-verify option, add skipVerify field to config interfaces
  • apps/pair-cli/src/commands/install/metadata.ts — Add --skip-verify to options list and notes
  • apps/pair-cli/src/kb-manager/kb-installer.ts — Add verification step in installKBFromLocalZip before extraction
  • apps/pair-cli/src/config/kb-resolver.ts — Pass skipVerify through resolveLocalDataset
  • apps/pair-cli/src/commands/install/parser.test.ts — Tests for --skip-verify parsing
  • apps/pair-cli/src/kb-manager/kb-installer.test.ts — Tests for verification integration

Dependencies:

• Technical: Verification checks from T-2 (checks/ modules), adm-zip
• Tasks: T-2 (needs verification engine)

Implementation Steps:

1. Add skipVerify?: boolean to InstallCommandConfigLocal (and optionally other variants for type consistency) in install/parser.ts
2. Add --skip-verify option parsing in parseInstallCommand
3. Add --skip-verify to installMetadata options array in install/metadata.ts
4. Create a verifyPackage(zipPath, fs) function (or import from kb-verify checks) that runs checksum + structure + manifest checks and returns pass/fail
5. In installKBFromLocalZip, add verification step before performExtractForZip: if skipVerify is false (default), call verifyPackage; on failure, throw "Package verification failed. Use --skip-verify to bypass."
6. Thread skipVerify parameter through resolveLocalDataset in kb-resolver.ts
7. If skipVerify is true, log warning "Skipping package verification (--skip-verify)" and proceed
8. Write unit tests for parser, integration tests for install-with-verify and skip-verify flows

Testing Strategy:

• Unit Tests: Parser correctly extracts --skip-verify flag; installKBFromLocalZip calls verification when skipVerify is false; verification is skipped when skipVerify is true
• Integration Tests: Full flow: package → install (auto-verify passes); package → corrupt → install (aborts); package → corrupt → install --skip-verify (proceeds with warning)
• Manual Testing: Run pair install --source ./valid.zip, pair install --source ./bad.zip, pair install --source ./bad.zip --skip-verify

Notes: The verification function should be importable from the kb-verify command's checks modules to avoid duplication. Consider extracting a shared verifyPackageZip(zipPath, fs) utility that both the standalone command and the install hook can call.

---

T-4: Update CLI documentation for kb-verify command and --skip-verify flag

Priority: P0 | Estimated Hours: 2h | Bounded Context: Knowledge Base Management

Summary: Update all relevant documentation files to reflect the new pair kb-verify standalone command and the --skip-verify flag on pair install.

Type: Documentation

Description: Multiple documentation files reference CLI commands and need updating. The new pair kb-verify command must be added to all command listings with full usage documentation. The --skip-verify flag must be added to the install command reference. Workflow guides should include verification examples and the package→verify→install roundtrip.

Acceptance Criteria:

• Primary deliverable: All doc files updated with kb-verify command reference and --skip-verify flag documentation
• Quality standard: Documentation is accurate, consistent with implementation, includes examples for both human-readable and JSON output modes
• Integration requirement: No code changes; documentation only
• Verification method: Manual review; all referenced flags and commands match implementation

Implementation Approach:

• Technical Design: Documentation-only changes across multiple files
• Bounded Context and Modules: KB Management — documentation
• Files to Modify:
  • docs/cli/commands.md — Add pair kb-verify command reference section with options (--json), verification checks, exit codes; add --skip-verify to install command options
  • docs/specs/cli-contracts.md — Add KbVerifyCommandConfig type, verification report JSON schema, updated InstallCommandConfig with skipVerify, updated ManifestMetadata with contentChecksum
  • docs/cli/help-examples.md — Add kb-verify usage examples (pass/fail scenarios), install with --skip-verify
  • apps/pair-cli/README.md — Update CLI feature overview with verification capability
  • docs/getting-started/02-cli-workflows.md — Add "Package Verification" workflow, update install workflow with auto-verification note
  • README.md — Add pair kb-verify to root command list

Dependencies:

• Technical: None
• Tasks: T-3 (implementation must be complete before documenting)

Implementation Steps:

1. Update docs/cli/commands.md: Add full pair kb-verify <package> command reference with options (--json), verification checks (checksum, structure, manifest), exit codes (0=pass, 1=fail); add --skip-verify to install command options
2. Update docs/specs/cli-contracts.md: Add KbVerifyCommandConfig type definition, verification report JSON schema, update InstallCommandConfig with skipVerify?: boolean, update ManifestMetadata with contentChecksum?: string
3. Update docs/cli/help-examples.md: Add verification examples (valid package, corrupted package, JSON output), install with --skip-verify example
4. Update apps/pair-cli/README.md: Add package verification feature to CLI overview
5. Update docs/getting-started/02-cli-workflows.md: Add "Verify KB Package" workflow section, update install workflow with auto-verification note
6. Update README.md: Add pair kb-verify to root command list
7. Verify all documentation is consistent with implementation

Testing Strategy:

• Manual review of all updated docs for accuracy and completeness
• Verify examples match the exact CLI flag names and output formats from implementation

Notes: Follow existing documentation style and formatting conventions. Include both human-readable and --json output examples for kb-verify. Document the automatic verification behavior during pair install and the --skip-verify escape hatch.

---

Refinement Completed By: Product Manager (AI-assisted)
Refinement Date: 2026-02-14
Review and Approval: Developer approved