> 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/phase21-session02-project-windows-skill-roi-defaults/spec.md).

# Session Specification

**Session ID**: `phase21-session02-project-windows-skill-roi-defaults` **Phase**: 21 - Non-Hermes v2.3 Usage Accuracy **Status**: Not Started **Created**: 2026-06-02

***

## 1. Session Overview

This session continues Phase 21 by correcting two misleading dashboard semantics left after the pricing and daily activity accuracy work. The aggregate currently emits `recentProjects` as a top-10 all-time project list, even though downstream copy treats the list as recent activity. This session will make `recentProjects` mean projects modified within the last seven days and add `allProjects` so long-tail workspace history remains available.

The session also restores practical per-skill saved-time defaults. AI OS currently returns zero minutes for every skill unless the operator manually configures a value, which makes ROI rows look valueless by default. This plan ports the v2.3 prefix-regex default table as the starting point and keeps a generic five-minute fallback for AI OS-only skills.

This is the natural next Phase 21 session because Session 01 already validated the adjacent pricing and daily session contract. Session 03 should wait until these local aggregate and ROI shapes settle, since its OAuth usage work touches the more sensitive usage-window path.

***

## 2. Objectives

1. Make aggregate `recentProjects` a true seven-day project activity window.
2. Add `allProjects` as a bounded long-tail project history contract.
3. Update typed live-data contracts, validation, examples, and consumers for additive project history support.
4. Port skill saved-time defaults with known prefix matches and a conservative generic fallback.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase15-session03-aggregate-orchestration-refactor` - Provides the modular aggregate orchestration layer this session extends.
* [x] `phase21-session01-pricing-daily-activity-accuracy` - Provides the current daily and pricing aggregate shape so project output changes do not conflict with in-flight Session 01 work.

### Required Tools/Knowledge

* Bun 1.3.14 project commands from `package.json`.
* Existing project activity aggregation in `scripts/lib/aggregate-orchestration.ts`.
* Existing project type and validation paths in `src/lib/live-data-types.ts` and `src/lib/validate-live-data.ts`.
* Current saved-time hook behavior in `src/lib/time-saved.ts`.
* v2.3 default minute table in `/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/lib/time-saved.ts`.

### Environment Requirements

* AI OS repo checked out at `/home/aiwithapex/projects/aios`.
* v2.3 source checkout available for reference only.
* No live credentials, generated private live data, or network access are required for implementation or tests.

***

## 4. Scope

### In Scope (MVP)

* An AI OS maintainer can generate `recentProjects` as projects active within the last seven days - filter by project `lastMs` against the aggregate run clock.
* An AI OS maintainer can inspect long-tail project history - emit bounded `allProjects` rows sorted by most recent activity.
* Browser consumers can parse old and new generated data - add optional `allProjects` support and preserve legacy payload compatibility.
* Workspace and settings transforms can still show long-tail project history - prefer `allProjects` where an all-workspaces view is intended and keep recency surfaces on `recentProjects`.
* ROI surfaces can show useful estimates without manual setup - port the skill-prefix defaults and five-minute fallback into `getDefaultMinutes`.
* Tests prove filtering, long-tail output, validation compatibility, default minute matching, unknown fallback, and ROI math.

### Out of Scope (Deferred)

* Reclassifying old projects as recent for convenience - Reason: the phase goal is count honesty.
* Hand-tuning every AI OS-specific skill estimate - Reason: this session ports a known starting table and a generic fallback only.
* Adding Antigravity saved-equivalent data - Reason: Phase 22 owns that after Antigravity detection data exists.
* Redesigning project or skill UI cards - Reason: this is a contract and behavior correction, not a visual pass.
* Adding Claude OAuth usage reads - Reason: Phase 21 Session 03 owns that sensitive network and credential path.

***

## 5. Technical Approach

### Architecture

Keep project list derivation near aggregate live-data assembly. Add focused helpers in `scripts/lib/aggregate-orchestration.ts` to build sanitized project rows from `parsed.projectActivity`, then split those rows into seven-day `recentProjects` and bounded `allProjects`. Use the aggregate run clock, not wall-clock calls scattered through map logic, so tests can pin behavior.

Keep the browser live-data contract additive. `allProjects` should be optional or defaulted so existing generated data remains valid. Shared project row typing should avoid duplicating `RecentProject` and `AllProject` shapes unless the implementation needs separate names for clarity.

Keep saved-time defaults in `src/lib/time-saved.ts`. The prefix-regex table can stay local to the module because the hook and pure ROI utilities already live there. User-configured localStorage and file overlays must continue to override defaults.

### Design Patterns

* Extract pure helpers, then test, then wire: project row building and saved-time matching should be directly testable.
* Additive contracts: `allProjects` is added without breaking old payloads.
* Typed degradation over throws: malformed project rows or invalid timestamps drop or degrade locally instead of blocking live-data validation.
* Deterministic ordering: project rows sort by newest activity first with a stable key tie-breaker.

### Technology Stack

* Bun 1.3.14 project runtime and test runner.
* TypeScript for script and browser code.
* Vitest for focused script, validation, transform, and ROI tests.
* Existing generated-data validation and sanitizer boundaries.

***

## 6. Deliverables

### Files to Create

| File                                                                                              | Purpose                                                         | Est. Lines |
| ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ---------- |
| `.spec_system/specs/phase21-session02-project-windows-skill-roi-defaults/implementation-notes.md` | Baseline notes, changes made, commands, and residual gaps       | \~120      |
| `.spec_system/specs/phase21-session02-project-windows-skill-roi-defaults/security-compliance.md`  | Privacy and generated-data sign-off for project and ROI changes | \~70       |

### Files to Modify

| File                                                    | Changes                                                                        | Est. Lines |
| ------------------------------------------------------- | ------------------------------------------------------------------------------ | ---------- |
| `scripts/lib/aggregate-orchestration.ts`                | Add project row helpers, seven-day `recentProjects`, and bounded `allProjects` | \~100      |
| `src/lib/live-data-types.ts`                            | Add optional `allProjects` contract and project timestamp fields               | \~20       |
| `src/lib/validate-live-data.ts`                         | Default and validate `allProjects` while preserving legacy payloads            | \~40       |
| `src/data/live-data.example.json`                       | Add sanitized project examples for recent and long-tail rows                   | \~20       |
| `src/lib/route-transforms.ts`                           | Prefer `allProjects` for all-workspace history where appropriate               | \~20       |
| `src/lib/transforms/workspaces.ts`                      | Keep workspace transform compatible with the shared project shape              | \~10       |
| `src/lib/time-saved.ts`                                 | Add prefix-regex default minute table and generic fallback                     | \~90       |
| `scripts/lib/__tests__/aggregate-orchestration.test.ts` | Cover seven-day recent filtering and long-tail output                          | \~80       |
| `src/lib/__tests__/nested-validation.test.ts`           | Cover `allProjects` validation and legacy compatibility                        | \~40       |
| `src/lib/__tests__/route-transforms.test.ts`            | Cover workspace/history consumers with `allProjects`                           | \~35       |
| `src/lib/__tests__/time-saved.test.ts`                  | Cover default minute table, fallback, overrides, and ROI totals                | \~50       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Projects older than seven days do not appear in `recentProjects`.
* [ ] Projects within seven days remain in `recentProjects` with stable sorting.
* [ ] `allProjects` emits long-tail project history with a documented cap.
* [ ] Browser live-data validation accepts new payloads and legacy payloads without `allProjects`.
* [ ] Workspace/history consumers can still show long-tail project data after `recentProjects` becomes a recent-only list.
* [ ] Known v2.3 skill prefixes receive planned default minute values.
* [ ] Unknown or AI OS-only skills receive a generic five-minute default.
* [ ] User-configured and file-configured saved-time values still override defaults.

### Testing Requirements

* [ ] Aggregate project row tests are written and passing.
* [ ] Validation tests cover new and legacy project payloads.
* [ ] Workspace or route transform tests cover `allProjects` fallback behavior.
* [ ] Time-saved tests cover known defaults, unknown fallback, override precedence, and ROI totals.
* [ ] Typecheck and relevant focused tests pass.

### Non-Functional Requirements

* [ ] No new client bundle dependency is added.
* [ ] Generated browser-visible project data remains sanitized and bounded.
* [ ] Project row sorting is deterministic.
* [ ] Default minute estimates are conservative and easy to override.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.

***

## 8. Implementation Notes

### Key Considerations

* `recentProjects` should mean activity within seven days of the aggregate run clock, not a top-10-ever list.
* `allProjects` should preserve access to historical project rows without leaking private path details beyond the existing sanitized project contract.
* Use `lastMs` from `parsed.projectActivity` for recency and sorting; document any fallback if a row lacks a finite timestamp.
* Saved-time defaults should not block user overrides. `minutes[name]` and file overlays must remain authoritative when configured.

### Potential Challenges

* Existing consumers may assume `recentProjects` means all workspace history: update only the all-history consumers to use `allProjects`, keeping home recency surfaces unchanged.
* Project path fields may be absent or sanitized: keep row builders defensive and deterministic.
* Regex defaults can overmatch unrelated skills: prefer anchored or prefix-oriented patterns matching v2.3 behavior.

### Relevant Considerations

* \[P01] **Bundle budget watch on 3D vendor chunks**: This session should add no client dependency and keep browser changes lightweight.
* \[P02] **Typed degradation over throws**: Invalid project rows or saved-time config should degrade locally instead of breaking aggregate output.
* \[P05] **Script-only runtime boundary**: Project aggregation stays in `scripts/lib/`; browser code consumes validated generated data only.
* \[P08] **Local agent privacy/readiness boundary**: Browser output must remain sanitized metadata and must not expose raw paths, prompts, logs, credentials, or workspace content.
* \[P15] **Full aggregate remains the compatibility command**: Keep `bun run aggregate` compatible while adding `allProjects`.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Recent-project cards keep showing old projects because the all-time list was renamed but not filtered.
* Workspaces lose long-tail rows when `recentProjects` becomes recent-only.
* ROI rows continue to show avoidable zero values because defaults are not used or user overrides no longer take precedence.

***

## 9. Testing Strategy

### Unit Tests

* Test aggregate project row helpers with projects inside the seven-day window, outside the window, missing timestamps, sanitized keys, ties, and more than the long-tail cap.
* Test `getDefaultMinutes` with known v2.3 prefixes, casing variants, empty strings, unknown names, and AI OS-only names.
* Test ROI totals using default minutes and caller-provided overrides.

### Integration Tests

* Test live-data validation for payloads with `allProjects`, payloads without it, malformed project arrays, and invalid project timestamp fields.
* Test route or workspace transforms to verify all-workspace history uses `allProjects` when present and falls back to `recentProjects` for legacy data.

### Manual Testing

* Run focused aggregate, validation, route-transform, and time-saved tests.
* Run app and script typechecks.
* Inspect generated example data shape for additive `allProjects` support.

### Edge Cases

* Empty project activity should emit empty `recentProjects` and `allProjects`.
* A project exactly seven days old should follow the documented boundary.
* Invalid project timestamps should not appear as recent.
* Unknown skills should get the five-minute fallback, while explicit zero user configuration should remain zero.

***

## 10. Dependencies

### External Libraries

* None added.

### Internal Dependencies

* `scripts/lib/session-scanner.ts` continues to provide `parsed.projectActivity`.
* `scripts/lib/aggregate-orchestration.ts` owns generated host/local live-data assembly.
* `src/lib/validate-live-data.ts` owns browser-safe defaulting and validation.
* `src/lib/time-saved.ts` owns saved-time defaults, overrides, and ROI helpers.

### Other Sessions

* **Depends on**: `phase21-session01-pricing-daily-activity-accuracy`.
* **Depended by**: `phase21-session03-authoritative-claude-usage-oauth` and Phase 22 Antigravity consumer work.

***

## Next Steps

Run the implement workflow step to begin AI-led implementation.


---

# 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/phase21-session02-project-windows-skill-roi-defaults/spec.md?ask=<question>&goal=<endgoal>
```

`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.