> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase38-session10-hunk-reconciliation-and-release-gate/spec.md). # Session Specification **Session ID**: `phase38-session10-hunk-reconciliation-and-release-gate` **Phase**: 38 - Claude OS v2.8.1 Semantic Port **Status**: Not Started **Created**: 2026-06-30 *** ## 1. Session Overview This session closes Phase 38 by proving that the semantic Claude OS v2.7 to v2.8.1 port is complete across every upstream changed path. Sessions 01 through 09 have implemented and validated the feature slices; this session verifies the remaining release condition that every upstream changed path and modified-file hunk has an explicit disposition. The work is evidence-first. It extracts upstream patch hunks, reconciles them against the adapted AI OS modules and previous session validation records, runs the required quality and security gates, and records any exact non-port blocker without inventing new feature scope. The session is next because the spec-system analyzer reports Phase 38 in progress, Sessions 01 through 09 completed, no current active session, and only `phase38-session10-hunk-reconciliation-and-release-gate` unfinished. *** ## 2. Objectives 1. Record a required disposition for all 39 upstream changed paths. 2. Record hunk-by-hunk dispositions for every modified upstream file. 3. Prove or correct final docs, product copy, security posture, and release gates for the Phase 38 port. 4. Preserve closeout evidence so Phase 38 can move to validation and PRD completion without relying on the old ongoing-projects plan. *** ## 3. Prerequisites ### Required Sessions * [x] `phase38-session01-tier-0-parity-fixes` - Memory counts, seed data, and Hermes graph/yolo semantics. * [x] `phase38-session02-platform-foundation` - Shared platform helpers. * [x] `phase38-session03-aggregate-and-dream-health` - Aggregate and Dream health metadata. * [x] `phase38-session04-dream-scheduling-and-setup` - Dream scheduling and setup warnings. * [x] `phase38-session05-runtime-bridge-hardening` - Runtime bridge and Vite local endpoint hardening. * [x] `phase38-session06-policy-docs-and-catalogs` - License, docs, mode, and model catalog policy. * [x] `phase38-session07-dream-engine-product-integration` - Dream engine product integration. * [x] `phase38-session08-voice-broker` - Local OpenAI Realtime token broker. * [x] `phase38-session09-intelligence-portal` - Hermes Intelligence portal and voice loop. ### Required Tools Or Knowledge * Bun 1.3.14, Node, git, jq, awk, rg, and Playwright Chromium. * Upstream comparison artifacts under `/home/aiwithapex/projects/claudeos/`. * Current Phase 38 PRD ledger and session validation reports. * AI OS local bridge, Dream, scheduler, Hermes, setup, and docs conventions. ### Environment Requirements * Repo root is `/home/aiwithapex/projects/aios`. * Upstream artifacts exist: `/home/aiwithapex/projects/claudeos/claude-os-v2.7_to_v2.8.1.full.patch`, `.name-status.txt`, `.stat.txt`, `.summary.txt`, and `_diff_findings.md`. * Real Windows and provider-credential checks should be run when available. When unavailable in this Linux-local run, the session must run faithful harnesses and record the exact unavailable proof as an environment limitation, not as a port implementation blocker. *** ## 4. Scope ### In Scope (MVP) * Maintainers can audit the Phase 38 port by changed path - create a complete disposition table for all 39 upstream paths using only the allowed statuses. * Maintainers can audit high-risk modified files by hunk - extract and reconcile hunks from the full patch for all modified upstream files. * Maintainers can trace superseded upstream behavior to AI OS replacements - record absolute AI OS replacement paths for every superseded item. * Maintainers can trace policy skips - name the resolved Phase 38 policy for every `skipped-resolved-policy` item. * Maintainers can trust release evidence - run lint, build, targeted tests, browser proof, docs sweeps, security checks, cross-platform harnesses, and artifact hygiene checks. * Users see truthful current behavior - correct stale docs or product copy found during the release gate without adding new feature scope. ### Out Of Scope (Deferred) * Reopening Phase 38 resolved policy decisions - Reason: the phase PRD fixes license, voice, config location, Dream ownership, and model catalog policy. * Adding new Dream, voice, Intelligence, scheduler, or bridge features - Reason: Session 10 is a reconciliation and release-gate session. * Replacing AI OS modules with upstream files wholesale - Reason: Phase 38 is a semantic port into diverged AI OS architecture. * Deleting evidence before validation - Reason: the reconciliation record is the closeout proof for the phase. *** ## 5. Technical Approach ### Architecture Use the Phase 38 PRD changed-path ledger as the complete path inventory. Use the upstream full patch and whole v2.8.1 files as source evidence, then map each item to current AI OS modules, tests, docs, and previous session validation reports. Store the durable closeout record in the Session 10 spec directory so the phase does not depend on a transient PR description. When a hunk is implemented in a different AI OS file, mark it `superseded` and include the absolute replacement path. When a hunk is intentionally not shipped because of resolved policy, mark it `skipped-resolved-policy` and name the policy from the Phase 38 PRD. When current docs or product copy overclaim behavior, correct the claim in place and record the proof. ### Design Patterns * Evidence ledger: every disposition cites a source path, target path, and validation command or prior session report. * AI OS ownership boundaries: Dream behavior stays in `scripts/lib/dream/**`, scheduler behavior stays in scheduler/install modules, Hermes chat stays on the existing bridge and SSE path, and setup/config use AI OS helpers. * Closeout artifacts beside specs: reconciliation, release-gate verification, and security evidence live under `.spec_system/specs/phase38-session10-hunk-reconciliation-and-release-gate/`. * Docs as current-state contracts: docs describe shipped behavior only and use example values shorter than real key patterns. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------- | | `.spec_system/specs/phase38-session10-hunk-reconciliation-and-release-gate/implementation-notes.md` | Task-by-task implementation and command evidence ledger. | \~180 | | `.spec_system/specs/phase38-session10-hunk-reconciliation-and-release-gate/hunk-reconciliation.md` | Complete 39-path disposition table plus modified-file hunk reconciliation. | \~320 | | `.spec_system/specs/phase38-session10-hunk-reconciliation-and-release-gate/release-gate-verification.md` | Final lint, build, targeted tests, browser proof, docs sweep, cross-platform, and blocker evidence. | \~220 | | `.spec_system/specs/phase38-session10-hunk-reconciliation-and-release-gate/security-compliance.md` | Session-level security and GDPR closeout for local bridge, provider key, voice, Dream, and docs boundaries. | \~160 | ### Files To Modify | File | Changes | Est. Lines | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ---------- | | `README.md` | Correct any stale sidecar, setup-step, Dream endpoint, or local voice claims found by the sweep. | \~20 | | `AGENTS.md` | Correct any Phase 38 current-state guidance that overclaims unproven behavior. | \~10 | | `docs/intelligence-view.md` | Correct any standalone voice or Hermes Intelligence claims that conflict with shipped behavior. | \~20 | | `docs/local-voice-setup.md` | Correct provider-key, `OPENAI_BASE_URL`, standalone voice-lab, and Hermes voice loop claims. | \~20 | | `docs/runbooks/ai-os-dream.md` | Correct Dream engine, scheduler, health, or verification wording found stale. | \~20 | | `docs/development.md` | Correct local endpoint or setup command references found stale. | \~20 | | `docs/commands.md` | Correct command and endpoint references found stale. | \~20 | | `scripts/setup.ts` | Correct user-facing setup warning text only if the release sweep finds platform-specific stale guidance. | \~15 | | `scripts/install-dream-cron.ts` | Correct user-facing scheduling warning text only if the release sweep finds platform-specific stale guidance. | \~15 | | `voice-lab/README.md` | Correct standalone voice-lab behavior claims if they conflict with the shipped sidecar. | \~20 | | `voice-lab/index.html` | Correct standalone voice-lab product copy or base handling only if the release sweep finds current behavior mismatch. | \~20 | *** ## 7. Success Criteria ### Functional Requirements * [ ] All 39 upstream changed paths have one allowed disposition status. * [ ] All modified upstream files have hunk-by-hunk disposition records. * [ ] Every `superseded` disposition names an absolute AI OS replacement path. * [ ] Every `skipped-resolved-policy` disposition names the resolved Phase 38 policy. * [ ] Stale docs and product copy found during closeout are corrected or recorded as exact non-port blockers. ### Testing Requirements * [ ] Targeted unit tests cover platform, aggregate, scheduler, Dream, setup, local bridge, voice broker, Hermes chat, Intelligence, and copy-sensitive behavior. * [ ] Playwright checks cover Home Dream generation, setup wizard, and Hermes Intelligence entry/recovery paths. * [ ] `bun run typecheck`, `bun run typecheck:scripts`, `bun run lint`, `bun run format:check`, `git diff --check`, and `bun run build` pass or exact unrelated blockers are recorded. ### Non-Functional Requirements * [ ] Local privileged endpoint checks cover loopback, Host-header, token, origin, body-size, and provider-key boundaries. * [ ] Browser-visible docs, fixtures, and product surfaces contain no raw private paths, tokens, account-auth material, transcripts, or generated private data. * [ ] Cross-platform proof uses real Windows checks when available and faithful harnesses plus explicit limitations when not available. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code and docs follow project conventions. * [ ] Normal user-facing surfaces contain product-facing copy only. * [ ] Release artifacts contain no unresolved blocker markers or open-decision markers. *** ## 8. Implementation Notes ### Working Assumptions * Session 10 is the only executable next session: the analyzer reports no active current session, Phase 38 in progress, Sessions 01 through 09 completed, and only the Session 10 stub incomplete. * The reconciliation record belongs in the Session 10 spec directory: the stub allows storing it next to Phase 38 artifacts or in a PR description, and a spec-directory artifact is durable, reviewable, and available before a PR is opened. * Prior session validation reports are valid evidence inputs but not automatic dispositions: they prove implemented slices, while Session 10 still maps each changed path and hunk explicitly. * Real Windows and provider-credential proof may be unavailable in the current local run. Planning can proceed because the PRD allows exact non-port blockers to be documented, and the repo already has platform, scheduler, voice, and bridge harnesses for faithful regression coverage. ### Conflict Resolutions * The upstream diff findings report includes stale upstream README/setup and standalone voice-lab caveats, while Sessions 06 through 09 may already have corrected AI OS behavior and docs. The release gate will trust current AI OS files and validated session evidence over upstream caveats, while preserving any still-current caveat as a required correction. * The upstream file layout conflicts with AI OS module ownership. The selected interpretation is the Phase 38 PRD rule: adapt semantics into AI OS modules, mark upstream-file copies as superseded or skipped when appropriate, and do not wholesale replace AI OS files. ### Key Considerations * Hunk reconciliation is the core deliverable; feature-level reading is not sufficient for high-risk modified files. * Release-gate commands may be expensive; record exact command output summaries in artifacts instead of relying on unstored terminal history. * Documentation corrections must avoid new claims about not-yet-proven voice, Dream, Intelligence, or scheduler behavior. ### Potential Challenges * Patch hunks map to refactored AI OS files: mitigate with absolute target paths and references to previous session validation evidence. * Some verification requires Windows or provider credentials: mitigate with harnesses, explicit environment limitations, and no false pass claims. * Large Vite and route diffs can hide endpoint drift: mitigate with targeted guard tests, route browser checks, and stale endpoint searches. ### Relevant Considerations * \[P01] **Old `claude-os-*` naming**: preserve compatibility aliases while documenting AI OS-owned settings and storage paths. * \[P04] **Hermes bridge guardrails must stay intact**: release checks must cover loopback, token, Host-header, body-size, path safety, and admin boundaries. * \[P11] **Scheduler state/log privacy boundary**: closeout evidence must expose only bounded statuses, durations, warnings, and freshness metadata. * \[P21] **Claude OAuth material stays script-only**: secret and auth scans must confirm token-shaped material stays out of browser state, generated data, and docs. * \[P26] **Knowledge Graph contract alignment**: Hermes graph grounding and Graphify bridge dispositions must trace through the shared contract. * \[P00] **Stack conventions**: use Bun, Vite 8, TanStack Start, React 19, Radix, and Cloudflare Worker constraints when running release gates. *** ## 9. Testing Strategy ### Unit Tests * Run focused script tests for platform, seed data, aggregate orchestration, scheduler install/handlers, Dream engine/config/execution/health, setup config, local-control-plane guards, Hermes admin bridge, voice broker, and voice launch bridge. * Run focused app tests for Dream hooks, setup config, Hermes admin hooks, Intelligence event mapping, voice lifecycle, portal, visualizers, and chat launcher behavior. ### Integration Tests * Run Playwright checks for `tests/e2e/home-dashboard.spec.ts`, `tests/e2e/setup-wizard.spec.ts`, and `tests/e2e/hermes-intelligence.spec.ts`. * Run docs and product-copy searches for stale sidecar endpoints, removed API routes, setup-step counts, Dream engine claims, local voice claims, and debug-only language in normal product surfaces. ### Runtime Verification * Run `bun run typecheck`, `bun run typecheck:scripts`, `bun run lint`, `bun run format:check`, `git diff --check`, `bun run build`, and targeted browser proof. * Run `bun audit --audit-level high`, `bun run runtime:check-private`, secret pattern sweeps, and local endpoint guard tests relevant to loopback, Host headers, token gating, origin checks, provider-key handling, and path safety. * Run real Windows and provider checks when available; otherwise record the exact unavailable environment and harness evidence. ### Edge Cases * Windows paths and usernames must be redacted without inflating counts. * Missing Hermes, missing Anthropic key, missing OpenAI key, bad voice token, rejected voice base URL, offline provider, and private-mode storage failures must have explicit evidence from tests, docs, or prior session validation. * Added upstream files that are intentionally not shipped must be marked `skipped-n/a`, `skipped-resolved-policy`, or `superseded`, not silently omitted. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase38-session01-tier-0-parity-fixes`, `phase38-session02-platform-foundation`, `phase38-session03-aggregate-and-dream-health`, `phase38-session04-dream-scheduling-and-setup`, `phase38-session05-runtime-bridge-hardening`, `phase38-session06-policy-docs-and-catalogs`, `phase38-session07-dream-engine-product-integration`, `phase38-session08-voice-broker`, and `phase38-session09-intelligence-portal`. * Depended by: Phase 38 validation, `updateprd`, and the phase-transition `audit` command. *** ## Next Steps Run the `implement` workflow step to begin reconciliation and release-gate execution. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase38-session10-hunk-reconciliation-and-release-gate/spec.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.