opportunities-extension/openspec/changes/archive/2026-10-31-document-project-baseline/design.md

Design

Context

See proposal.md for motivation and the capability inventory. This is the initial specification baseline for the current checkout, whose package/build version is 1.1.0. The checkout includes behavior added after the 1.1.0 release; the baseline must not be presented as an exact description of that tag.

OpenSpec uses the existing spec-driven schema. Its main specification directory is empty. The change introduces behavioral contracts, not runtime features. A design is warranted because reconciling documentation spans authentication, data loading, storage and UI boundaries and requires explicit decisions about conflicting historical descriptions.

The application uses factory-based JavaScript modules. src/content/application.js and src/background/application.js compose collaborators; scripts/sources.cjs and scripts/compose.cjs assemble isolated classic scripts. scripts/build.mjs generates Manifest V3 distributions for Chromium/Edge and Firefox with different background entry points. No framework migration is involved.

Goals / Non-Goals

Goals:

• Preserve externally observable behavior in requirements with testable scenarios.
• Make source/test evidence discoverable without putting internal function names into normative requirements.
• Reconcile README and architecture descriptions with current behavior during application.
• Establish the distinction between a proposed baseline in this change and durable specifications promoted after review and completion.

Non-Goals:

• Fix unrelated runtime defects, add retries, migrate storage, alter permissions or change endpoints.
• Declare every scenario already covered by automated or live-browser tests.
• Copy the full README into configuration, customize the OpenSpec schema, or add machine-specific executable paths as project requirements.
• Change release history, regenerate packages for documentation edits, or publish a version.

Decisions

1. Bootstrap existing capabilities explicitly

The specs use ADDED Requirements because the OpenSpec inventory is empty. This means new specification coverage, not newly implemented product behavior. Each spec has its own Purpose and cohesive domain boundary. A documentation-only skip_specs change would not fulfill the user's request to establish functional artifacts, while a single all-project spec would make future deltas difficult to review.

2. Resolve documentation conflicts against observable implementation

Use current source plus relevant regression scenarios to determine the baseline. Historical release notes explain evolution; they do not override the current implementation. Tests are supporting evidence, not proof of live Oracle compatibility. Unverified aspirations must not be silently converted into requirements or implemented during baseline application.

3. Preserve runtime and storage distinctions

Document content/background messaging and browser API adaptation without changing them. Distinguish page localStorage, sessionStorage, extension storage, in-memory caches and extension-owned IndexedDB. In particular, debug display masking does not guarantee that stored records exclude credentials. A blanket statement that all production credentials remain only in memory would contradict the retained debug response behavior.

The principal flow to describe is:

identity and session preparation
          |
          v
Token Relay --> Opportunity saved search --> opportunity pages
                                                   |
                                                   v
                                            display ready list
                                                   |
                         +-------------------------+------------------+
                         v                                            v
                 CRM SR background pages                      product enrichment
                         |                                            |
                         +-------- SR success/reuse + products -------+
                                                   |
                                                   v
                                          Workload Actions

Workloads additionally depend on account/product identifiers. This diagram does not prescribe a new global request scheduler. Profile gates apply to the data operations they control; concurrent session bootstrap is not itself a Manage Time data request.

4. Keep documentation responsibilities separate

• README.md: concise product overview, supported entry points, major features, development/build/test/loading instructions and links to deeper documentation.
• docs/architecture.md: execution contexts, transport/credential boundaries, storage ownership, actual permissions and verification limits.
• RELEASE_NOTES.md: historical release record; preserve prior descriptions as history rather than rewriting old releases to match today.
• openspec/specs/: durable behavioral contracts after the baseline is reviewed, applied and archived.
• This change: proposal, design, initial delta specs and actionable documentation/verification tasks.

Replacing the README entirely with OpenSpec would make ordinary setup less accessible. Duplicating complete behavioral contracts in both places would make future drift more likely. Link from documentation instead, retaining only the usage detail needed by its audience.

5. Use minimal configuration

Retain openspec/config.yaml as initialized. Discoverable code structure and local CLI locations do not need to become project context rules. All artifacts in this change are English to match the extension documentation; discussion with the user remains Portuguese. Any later configuration customization is a separate explicit decision.

Evidence Map

Paths below are relative to the repository root. These identify where to review behavior, not a claim that every specification scenario has already been executed.

Capability	Primary source evidence	Existing regression evidence
session-authentication	src/auth/current-user.js, src/auth/consumer-session.js, src/auth/spa-page.js, src/background/contracts.js, src/content/application.js	tests/currentUser.test.cjs, tests/spaSessionWait.test.cjs, tests/spaSessionReload.test.cjs, tests/srSessionPreparation.test.cjs
opportunity-exploration	src/services/fusion/opportunities.js, src/features/opportunities/controller.js, filters.js, table.js, fiscal-periods.js	tests/dependentFilters.test.cjs, tests/allOpportunityFilters.test.cjs, tests/opportunityTable.test.cjs, tests/dashboardTotals.test.cjs, tests/characterization.test.cjs
opportunity-calendar	src/features/opportunities/calendar.js, src/features/opportunities/styles.css	tests/opportunityCalendar.test.cjs plus installed-browser visual inspection for week positioning
product-workloads	src/features/products/details.js, workloads.js, workloads-cache.js, ramp-projection.js, forecast-update.js	tests/workloads.test.cjs, tests/ramp-projection.test.cjs, tests/workload-forecast-update.test.cjs, tests/badgeIcons.test.cjs
service-requests	src/services/fusion/crm-service-requests.js, src/features/opportunities/crm-service-requests.js, crm-sr-form.js, internal-sr-session.js, internal-sr-form.js, src/features/service-requests/	tests/srRequestPriority.test.cjs, tests/crmServiceRequests.test.cjs, tests/activityProgress.test.cjs, tests/internalSrRecovery.test.cjs, tests/srCreate.test.cjs, tests/serviceRequests.test.cjs
workload-actions	src/features/opportunities/product-activities.js, workload-actions.js, workload-action-form.js	tests/productActivities.test.cjs, tests/workloadActions.test.cjs, tests/workloadActionForm.test.cjs
manage-time	src/features/manage-time/view.js, src/services/fusion/time-entries.js, src/content/application.js	tests/manageTime.test.cjs, tests/currentUser.test.cjs
customer-insights	src/features/install-base/, src/features/consumption/, src/features/ratecard/, src/services/spa/	tests/installBase.test.cjs, tests/consumptionTrend.test.cjs, tests/consumptionPlanDetail.test.cjs, tests/ratecard.test.cjs
organization-charts	src/features/org-chart/model.js, storage.js, view.js, src/services/fusion/account-contact.js	tests/orgChart.test.cjs, tests/accountContact.test.cjs
extension-shell	src/content/fusion-page.js, shortcut-intent.js, modal.js, dialog-drag.js, src/features/opportunities/print.js	tests/shortcutLink.test.cjs, tests/bookmarkShortcut.test.cjs, tests/bookmarkHint.test.cjs, tests/modalShortcuts.test.cjs, tests/dialogDrag.test.cjs
preferences-cache	src/features/preferences/, src/features/opportunities/activity-cache.js, refresh-all.js, src/features/products/cache.js	tests/tableSorting.test.cjs, tests/activityCache.test.cjs, tests/formRequestCache.test.cjs, tests/refreshAll.test.cjs
request-debugging	src/features/debug/state.js, content-log.js, content-view.js, src/services/fusion/opportunities.js	tests/debugStorage.test.cjs, tests/debugTabs.test.cjs, tests/productsDebug.test.cjs

Documentation Reconciliation

During application, make the following concrete corrections, verifying the cited implementation again before editing:

Document/topic	Required reconciliation
README Opportunity Views	Replace month/week navigation and overflow links with Reference-bounded scrolling months, all daily cards and current-week positioning.
README and architecture AI references	Remove descriptions of active AI summaries, Sales Common token acquisition and AI suites/modules. Preserve historical release notes.
README authentication	Use the current SPA UI bootstrap URL; distinguish successful identity reuse from session recovery attempts.
README SR/Actions ordering	Describe opportunities displayed first, progressive SR enrichment and Actions depending on product identifiers and SR success/reuse. Remove the assertion that SR must wait for product completion.
README activity cache	Reconcile claims that cached products never allow activity network requests: the current product-activity orchestration permits cache-miss lookups. Retain timestamp/principal cache scoping where implemented.
README access restrictions	Include Manage Time UI and data gates for SALES_REP. Do not claim that all independent SR session bootstrap is disabled by that role.
README Organization Charts	Include alphanumeric PartyNumber, on-demand contact refresh, transient email, contact creation and fully paginated contact opportunities.
README capabilities	Cover dependent Customer/Owner options, Booking/Workload filters, printing, bookmark shortcuts/hints and draggable headers.
README Rate Card	Document Order Number multiselect and inspect final composed styles before describing responsive width; a single earlier CSS min-width rule is not proof of the effective layout.
Architecture contexts/permissions	Reflect the early shortcut-intent script, SPA readiness script and generated manifest permissions/hosts from scripts/build.mjs, including bookmarks and SR integration access.
Architecture request lifecycle	Remove the blanket claim that no AbortController is used; distinguish Token Relay timeouts from stale-response suppression and requests continuing behind a hidden modal.
Architecture storage	Describe debug localStorage and its reset boundary, preferences/sort storage, activity/product/workload caching, identity/session reuse and org-chart IndexedDB. Distinguish UI masking from storage confidentiality.
Architecture legacy contracts	Remove active RENEWALS and AI contracts; explain dynamic saved-search selection for Opportunity and CRM SR independently.

Risks / Trade-offs

• [A baseline can accidentally promise unimplemented behavior] -> Trace each requirement to source and scenarios; raise discrepancies rather than adding runtime fixes under this documentation change.
• [Documentation already contains contradictory cache and session claims] -> Review the composition root and effective call paths, not just an isolated helper or old prose.
• [Synthetic tests cannot verify Oracle endpoint availability or browser SSO] -> Record automated validation separately from installed-browser/live-service verification; never label the latter passed without execution.
• [Debug records can contain sensitive values] -> Describe the current behavior accurately without embedding real tokens, customer responses or personal data in artifacts. Any storage-hardening change is separate work.
• [Broad baseline coverage can obscure ownership] -> Keep twelve cohesive capability files and a source/test evidence map; do not duplicate implementation details in requirements.

Migration Plan

1. Review the proposed contracts against the current checkout and resolve documentation discrepancies without changing runtime behavior.
2. Apply the README and architecture corrections; keep the existing principal README title and separate release history.
3. Validate the OpenSpec change strictly, verify build consistency and run the relevant existing synthetic checks. Record any failures or browser-verification gaps honestly.
4. Complete the documentation tasks, then use the archive workflow to promote the initial specs to openspec/specs/. Do not manually copy them early or mark the change applied merely because planning is complete.
5. For subsequent behavior changes, identify the affected baseline capability, create delta requirements, implement and verify, then archive.

No runtime deployment or data migration is required. Before archival, rollback consists of reverting the documentation edits and removing the proposed change through an explicit repository operation. After archival, restore/revise documentation and specifications together through a follow-up change; never delete user data or rewrite release history as part of this baseline.

Application Review Record

Reviewed on 2026-10-31 against the current checkout:

• All twelve proposed capabilities have a matching specification file. Structural review found 69 requirements and 88 scenarios; every requirement has a scenario with a trigger and outcome.
• README.md and docs/architecture.md now distinguish opportunity-first loading, background SR progress, product-dependent Actions and cache-miss activity reads from the superseded loading descriptions.
• The documentation distinguishes page storage, extension storage and chart IndexedDB; it explicitly states that debug masking does not remove retained originals from storage.
• Review confirmed the current SPA bootstrap, role gates, dynamic saved searches, contact identifiers and composed Rate Card styles without changing their implementation. No additional runtime behavior was introduced to satisfy the baseline.
• Task-specific synthetic suites passed as their documentation groups were applied. Local documentation links resolve.
• No installed-browser visual test or live Oracle authentication/read/write was performed. Calendar sizing, responsive layouts, dragging, print pagination and live endpoint availability retain that verification limitation; synthetic scenario coverage is not a claim of end-to-end certification.

Final application checks on 2026-10-31:

• openspec validate document-project-baseline --strict: passed.
• node scripts/build.mjs --check: passed; existing Chromium/Edge and Firefox outputs match the source.
• node scripts/test.cjs using Node 22.15.0: 54 test files, 462 tests passed, zero failed.
• git diff --check and a whitespace scan of the new OpenSpec Markdown files: passed.
• The tracked diff contains only README.md and docs/architecture.md. The change's task/review records are updated in the already-created OpenSpec tree; the preexisting untracked .agents/ installation is untouched.
• Source, tests, build scripts, distributions, package version, release history and OpenSpec configuration are unchanged. The change is applied but not archived; the main spec inventory remains unpopulated until the separate archive workflow.

Archive Record

On 2026-10-31, after explicit approval to synchronize and archive, all twelve capabilities were promoted to openspec/specs/. Their authored Purpose sections, 69 requirements and 88 scenarios were preserved; the main files use canonical Specification titles and Requirements sections without delta-operation headers. All twelve main specifications passed openspec validate --specs --strict. The completed change (13/13 tasks, schema spec-driven) was moved to openspec/changes/archive/2026-10-31-document-project-baseline/, including its .openspec.yaml. README and architecture navigation now point to the durable specifications and archived evidence. This archive record supersedes the pre-archive inventory status in the application checks above.