diff --git a/openspec/changes/archive/2026-10-31-configure-project-context/.openspec.yaml b/openspec/changes/archive/2026-10-31-configure-project-context/.openspec.yaml new file mode 100644 index 0000000..6257ed6 --- /dev/null +++ b/openspec/changes/archive/2026-10-31-configure-project-context/.openspec.yaml @@ -0,0 +1,3 @@ +schema: spec-driven +created: 2026-10-31 +skip_specs: true diff --git a/openspec/changes/archive/2026-10-31-configure-project-context/design.md b/openspec/changes/archive/2026-10-31-configure-project-context/design.md new file mode 100644 index 0000000..393f9a2 --- /dev/null +++ b/openspec/changes/archive/2026-10-31-configure-project-context/design.md @@ -0,0 +1,100 @@ +# Design + +## Context + +See [proposal.md](proposal.md) for motivation. The current config selects `spec-driven` and contains commented examples only. README documents workflow and usage; `docs/architecture.md` documents runtime boundaries; the twelve specs are the reviewed behavioral baseline; RELEASE_NOTES records releases. + +Read-only inspection covered those documents, `package.json`, `scripts/build.mjs`, `scripts/test.cjs` and the installed OpenSpec configuration parser. The installed CLI accepts `context` as a string, `rules` as artifact-keyed arrays of strings and `operations.apply/archive.guidance` as arrays of strings. No custom schema, store or dependency is necessary. Design is included to make the exact configuration and its cross-workflow effects reviewable before apply. + +## Goals / Non-Goals + +**Goals:** Make durable conventions available to future planning and implementation; separate shared context, artifact rules and advisory execution guidance; keep the candidate valid for the installed CLI. + +**Non-Goals:** Turn config into a second README, freeze current endpoint URLs or module inventories, introduce executable policy enforcement, or make archive mean release. No main specification needs modification. + +## Decisions + +### Keep the standard schema and local root + +Retain `schema: spec-driven`. Do not add a `store`, custom workflow or schema override: the existing local workflow already supports proposal/design/tasks and explicit spec skipping for tooling-only changes. + +### Keep only stable constraints in shared context + +Use a short context with documentation references, English output conventions, browser compatibility and the user's release expectations. Detailed APIs, role gates, storage keys, module layouts, test counts and URLs stay in the existing documents. This avoids a copied baseline drifting independently. + +English artifacts and UI do not require English conversation: communication can continue in Portuguese. The Firefox-only XPI expectation applies when a release is requested; it does not drop Chromium/Edge support or authorize a release during ordinary work. + +### Separate artifact guidance from operation guidance + +`rules` describe the content of proposal, design, specs and tasks. `operations` hold apply/archive advice and do not override explicit choices, skill steps or CLI checks. Hardcoding developer-machine paths or adding redundant approval gates was considered and rejected. + +### Proposed replacement for openspec/config.yaml + +This block is the reviewed candidate, not an applied configuration. Replace the config with it only during apply. + +```yaml +schema: spec-driven + +context: | + Opportunities Extension supports Oracle Fusion workflows in Chromium/Edge and Firefox. + Write OpenSpec artifacts and extension-authored UI text in English; preserve service-provided names. + Use openspec/specs/ for behavioral contracts, docs/architecture.md for execution and storage + boundaries, README.md for setup and usage, and RELEASE_NOTES.md for release history. + Preserve both browser targets and the existing extension design system unless the change + explicitly proposes a compatibility or presentation change. + When a release is requested, include a valid Firefox XPI; XPI packaging is Firefox-only. + Keep the README main title as Opportunities Extension and release history in RELEASE_NOTES.md. + OpenSpec archival and product release are separate operations. + +rules: + proposal: + - Identify affected existing capabilities and distinguish observed behavior from proposed changes. + - State scope, non-goals and compatibility impact; do not introduce product requirements for tooling-only changes. + design: + - Reference the relevant architecture contracts instead of duplicating their inventories. + - For affected integrations, describe request ordering, credentials, pagination, retries and stale-response handling. + - For affected persistence, describe ownership, identity scope, invalidation and migration or rollback needs. + - For UI changes, identify shared components and relevant loading, empty, failure and theme behavior. + specs: + - Describe observable behavior with testable scenarios; keep implementation steps and module wiring in design and tasks. + - Use synthetic identifiers and examples; never embed real tokens, cookies or personal contact data. + tasks: + - Tie each task to a concrete deliverable and include verification proportional to the affected behavior. + - For source changes, include relevant synthetic tests, regeneration of affected browser outputs and a build consistency check. + - Record installed-browser and live Oracle checks separately from synthetic tests, including checks not performed. + - Include version, release notes and Firefox XPI work only when release delivery is part of the requested scope. + +operations: + apply: + guidance: + - Edit source modules and regenerate distributions through the build script; do not hand-edit generated bundles. + - Use synthetic data for automated checks and avoid incidental writes to live Oracle services during validation. + - Run focused checks for the change; use node scripts/test.cjs for integration verification of runtime changes and node scripts/build.mjs --check for generated-output consistency. + - Report what changed, verification results and material limitations without claiming unperformed browser or live-service validation. + archive: + guidance: + - Check documentation links when moving a change and preserve the distinction between archived evidence and current specifications. + - Summarize task completion, specification synchronization and the final archive location; do not treat archival as a product release. +``` + +### Validation approach + +Parse the candidate as YAML and validate it with the installed OpenSpec configuration schema before apply. The context must be a nonempty UTF-8 string below 51,200 bytes; all artifact rule and operation guidance entries must be nonempty strings. Use only supported artifact and operation identifiers. + +After apply, inspect `openspec context --json` and `openspec instructions proposal/design/tasks/apply/archive --change configure-project-context --json` as separate calls. Confirm context is delivered, artifact rules occur only on their matching artifact, and apply/archive advice is exposed as `operationGuidance`. For specs rules, inspect the parsed configuration rather than creating fictitious delta files or removing `skip_specs` just to probe a skipped artifact. + +Run `openspec validate configure-project-context --strict`, `openspec validate --specs --strict` and `git diff --check`. A config-only change does not justify rebuilding distributions or running all runtime tests. Preserve baseline runtime verification as historical evidence, not a new test claim. + +## Risks / Trade-offs + +- [Context becomes stale] -> Keep it short and reference existing authoritative files; omit current version, endpoint lists, absolute paths and test totals. +- [Guidance is mistaken for enforcement] -> Explain that config is prompt-level guidance; it does not guarantee tests, safe storage or API authorization. +- [New rules overconstrain unrelated work] -> Scope design rules to affected integrations/persistence/UI and verification to the change's impact. +- [A future CLI changes supported fields] -> Validate parsing and actual instruction delivery with the installed CLI when applying or upgrading. +- [Release expectations are misread as authorization] -> Keep release tasks conditional and explicitly separate archive from release. + +## Migration Plan + +During apply, replace only `openspec/config.yaml` with the candidate, verify configuration consumption and complete the tracked tasks. Existing specs, archived artifacts and runtime data need no migration. Future instruction reads receive the new guidance; existing artifacts are not rewritten automatically. + +Rollback restores the prior config from the implementation diff without deleting changes or specs. No runtime deployment, data migration or browser reinstallation is required. diff --git a/openspec/changes/archive/2026-10-31-configure-project-context/proposal.md b/openspec/changes/archive/2026-10-31-configure-project-context/proposal.md new file mode 100644 index 0000000..d21d0b3 --- /dev/null +++ b/openspec/changes/archive/2026-10-31-configure-project-context/proposal.md @@ -0,0 +1,30 @@ +# Proposal + +## Why + +The behavioral baseline is now archived, but OpenSpec configuration still contains only the default schema and commented examples. Future changes need concise, durable project constraints and artifact guidance without repeatedly reconstructing decisions from conversation history or duplicating the twelve specifications. + +## What Changes + +- Keep `schema: spec-driven` and the repository-local planning root. +- Add a short English `context` capturing documentation ownership, English UI/artifacts, browser compatibility, established presentation conventions and the Firefox XPI release expectation. +- Add focused `rules` for proposal, design, specs and tasks; keep implementation guidance in the supported `operations.apply` and `operations.archive` sections. +- Provide the exact proposed YAML in the design for review before replacing `openspec/config.yaml` during apply. +- Validate configuration parsing and instruction delivery without changing extension behavior. + +## Capabilities + +### New Capabilities + +None. This change configures development tooling rather than introducing product behavior. + +### Modified Capabilities + +None. The twelve existing capabilities remain unchanged. This tooling-only change declares `skip_specs: true`; no delta specification is required or generated. + +## Impact + +- Implementation target: `openspec/config.yaml` only, plus this change's completion records. +- OpenSpec agents receive project context, per-artifact rules and advisory apply/archive guidance. +- No source, browser permissions, API contracts, storage data, generated distributions, dependencies, version numbers or release history change. +- Out of scope: new workflows/schemas, external stores, runtime changes, releasing a version, generating an XPI now, or automatically applying/archiving future changes. diff --git a/openspec/changes/archive/2026-10-31-configure-project-context/tasks.md b/openspec/changes/archive/2026-10-31-configure-project-context/tasks.md new file mode 100644 index 0000000..4d16df3 --- /dev/null +++ b/openspec/changes/archive/2026-10-31-configure-project-context/tasks.md @@ -0,0 +1,15 @@ +# Tasks + +## 1. Apply the reviewed configuration + +- [x] 1.1 Replace `openspec/config.yaml` with the YAML candidate in design.md, preserving `schema: spec-driven`; verify its parsed values match the candidate, context is below 51,200 UTF-8 bytes, rules and guidance are nonempty string arrays, and only supported artifact/operation keys are used. Record the configuration validation result in the change. +- [x] 1.2 Confirm instruction delivery using `openspec context --json` and separate `openspec instructions` calls for proposal, design, tasks, apply and archive on this change; verify the root is unchanged, context is present, artifact rules match their artifact and operation advice is separate. Verify specs rules in parsed config without creating delta files for this `skip_specs` change; record results and the advisory nature of config guidance. + +## 2. Verify scope and integration + +- [x] 2.1 Run `openspec validate configure-project-context --strict` and `openspec validate --specs --strict`; verify the change is valid with no deltas and all twelve existing capabilities remain valid. +- [x] 2.2 Run `git diff --check` and compare the final changes against the apply starting state; confirm only config and this change's completion records changed, no machine-specific paths or live credentials were introduced, and no runtime tests/build/browser checks are claimed as performed for this config-only update. + +## Workflow follow-up + +- Archive only after application and review; this change has no delta specs to synchronize and does not constitute a release. diff --git a/openspec/changes/archive/2026-10-31-configure-project-context/verification.md b/openspec/changes/archive/2026-10-31-configure-project-context/verification.md new file mode 100644 index 0000000..812765a --- /dev/null +++ b/openspec/changes/archive/2026-10-31-configure-project-context/verification.md @@ -0,0 +1,8 @@ +# Application Verification + +- Configuration parsed with the installed OpenSpec YAML parser and ProjectConfigSchema. The applied values match the design candidate exactly. +- Schema remains spec-driven; context is 762 UTF-8 bytes. All four artifact rule groups and both operation guidance groups contain nonempty strings and supported keys. +- CLI context and separate proposal/design/tasks/apply/archive instruction lookups passed. Root is unchanged; context matches after the artifact loader's documented trim normalization; artifact rules match their artifact and operationGuidance remains separate. Specs rules were checked in parsed config; no delta files were created. +- Configuration advice is prompt-level guidance, not executable enforcement. Source regeneration and runtime test guidance are inapplicable to this configuration-only edit; no source or generated output was changed. No Oracle requests were sent. +- Strict validation passed for configure-project-context with zero deltas (skip_specs), and for all twelve existing main specifications. +- Final scope review and git diff --check passed. Relative to the initial clean tracked state plus the preexisting change directory, edits are confined to openspec/config.yaml, task completion markers and this verification record. No machine-specific paths or live credentials were added to config. Runtime tests, builds, installed-browser checks and live-service checks were not run because no runtime behavior or generated output changed. diff --git a/openspec/config.yaml b/openspec/config.yaml index 2805cb6..0091df4 100644 --- a/openspec/config.yaml +++ b/openspec/config.yaml @@ -1,32 +1,42 @@ schema: spec-driven -# Project context (optional) -# Add only constraints that should guide OpenSpec artifacts and workflows. -# Include constraints an agent cannot infer by reading the code. -# Keep general project documentation and discoverable codebase facts out. -# Example: -# context: | -# Designs and tasks must cover Windows, macOS, and Linux -# Write all artifacts in Spanish +context: | + Opportunities Extension supports Oracle Fusion workflows in Chromium/Edge and Firefox. + Write OpenSpec artifacts and extension-authored UI text in English; preserve service-provided names. + Use openspec/specs/ for behavioral contracts, docs/architecture.md for execution and storage + boundaries, README.md for setup and usage, and RELEASE_NOTES.md for release history. + Preserve both browser targets and the existing extension design system unless the change + explicitly proposes a compatibility or presentation change. + When a release is requested, include a valid Firefox XPI; XPI packaging is Firefox-only. + Keep the README main title as Opportunities Extension and release history in RELEASE_NOTES.md. + OpenSpec archival and product release are separate operations. -# Per-artifact rules (optional) -# Add custom rules for specific artifacts. -# Example: -# rules: -# proposal: -# - Keep proposals under 500 words -# - Always state what is out of scope -# tasks: -# - Break tasks into chunks of max 2 hours +rules: + proposal: + - Identify affected existing capabilities and distinguish observed behavior from proposed changes. + - State scope, non-goals and compatibility impact; do not introduce product requirements for tooling-only changes. + design: + - Reference the relevant architecture contracts instead of duplicating their inventories. + - For affected integrations, describe request ordering, credentials, pagination, retries and stale-response handling. + - For affected persistence, describe ownership, identity scope, invalidation and migration or rollback needs. + - For UI changes, identify shared components and relevant loading, empty, failure and theme behavior. + specs: + - Describe observable behavior with testable scenarios; keep implementation steps and module wiring in design and tasks. + - Use synthetic identifiers and examples; never embed real tokens, cookies or personal contact data. + tasks: + - Tie each task to a concrete deliverable and include verification proportional to the affected behavior. + - For source changes, include relevant synthetic tests, regeneration of affected browser outputs and a build consistency check. + - Record installed-browser and live Oracle checks separately from synthetic tests, including checks not performed. + - Include version, release notes and Firefox XPI work only when release delivery is part of the requested scope. -# Per-operation guidance (optional) -# Add advisory guidance for how apply and archive work should be conducted. -# This is separate from artifact rules above. -# Example: -# operations: -# apply: -# guidance: -# - Keep test summaries concise -# archive: -# guidance: -# - Summarize the archive outcome before finishing +operations: + apply: + guidance: + - Edit source modules and regenerate distributions through the build script; do not hand-edit generated bundles. + - Use synthetic data for automated checks and avoid incidental writes to live Oracle services during validation. + - Run focused checks for the change; use node scripts/test.cjs for integration verification of runtime changes and node scripts/build.mjs --check for generated-output consistency. + - Report what changed, verification results and material limitations without claiming unperformed browser or live-service validation. + archive: + guidance: + - Check documentation links when moving a change and preserve the distinction between archived evidence and current specifications. + - Summarize task completion, specification synchronization and the final archive location; do not treat archival as a product release.