feat(openspec): backport existing functionality into baseline specs#21
Merged
feat(openspec): backport existing functionality into baseline specs#21
Conversation
Add 15 OpenSpec specification files under openspec/specs/ that document the existing behavior of all memex-core modules as baseline requirements. These specs serve as the authoritative reference for current functionality and will be the foundation for future change proposals. Specs organized by module: - embeddings: EmbeddingProvider, Local/OpenAI providers, cosineSimilarity - skill-index: SkillIndex, parseFrontmatter, parseMemoryFile, search - cache: Cache v2 schema, atomic writes, mtime-gating - config: DEFAULT_CORE_CONFIG, resolveCoreConfig - session: SessionTracker, InMemorySessionTracker - telemetry: recordMatch, recordObservation, formatTelemetryReport - traces: TraceAccumulator, writeTrace - sync: initSyncRepo, syncPull, syncCommitAndPush, conflict resolution - sync-migration: version markers, migrateProjectIdsToLowercase, runSyncMigrations - project-mapping: resolveProjectId, normalizeGitUrl, findMatchingProjectMemoryDirs - project-registry: loadRegistry, saveRegistry, registerProject - file-lock: acquireLock, withFileLock - git-helpers: git wrapper, isGitRepo, hasRemote, hasCommits, getDefaultBranch - path-encoder: encodeProjectPath - types: all TypeScript interfaces and type definitions
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 15 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="openspec/specs/file-lock/spec.md">
<violation number="1" location="openspec/specs/file-lock/spec.md:5">
P2: The requirement says "exponential backoff" but the implementation uses a fixed 50ms retry interval. This mismatch could mislead future implementers into adding exponential backoff where none currently exists. Change to "fixed-interval retry" to match the actual code.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.
|
|
||
| ### Requirement: Advisory file locking via mkdir | ||
|
|
||
| `acquireLock(filePath)` SHALL create an advisory lock directory at `${filePath}.lock` using `mkdir`, which is atomic on all platforms. It returns an unlock function that removes the lock directory. If the lock already exists, it retries with exponential backoff until a timeout is reached. |
There was a problem hiding this comment.
P2: The requirement says "exponential backoff" but the implementation uses a fixed 50ms retry interval. This mismatch could mislead future implementers into adding exponential backoff where none currently exists. Change to "fixed-interval retry" to match the actual code.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At openspec/specs/file-lock/spec.md, line 5:
<comment>The requirement says "exponential backoff" but the implementation uses a fixed 50ms retry interval. This mismatch could mislead future implementers into adding exponential backoff where none currently exists. Change to "fixed-interval retry" to match the actual code.</comment>
<file context>
@@ -0,0 +1,44 @@
+
+### Requirement: Advisory file locking via mkdir
+
+`acquireLock(filePath)` SHALL create an advisory lock directory at `${filePath}.lock` using `mkdir`, which is atomic on all platforms. It returns an unlock function that removes the lock directory. If the lock already exists, it retries with exponential backoff until a timeout is reached.
+
+#### Scenario: Lock acquired on first attempt
</file context>
Code reviewNo issues found. Checked for bugs and CLAUDE.md compliance. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Backports all existing memex-core functionality into 15 OpenSpec specification files under
openspec/specs/, organized by module for maintainability. These specs document current behavior as baseline requirements using the WHEN/THEN scenario format, serving as the authoritative reference for future change proposals.Specs Added (15 modules, 89 requirements, 161 scenarios)
Key Decisions
openspec/specs/, making it easy to find and update specs alongside the code they describe## Requirements(not## ADDED Requirements) since these document existing behavior, not new featuresRelationship to Existing Specs
The
openspec/changes/lowercase-project-ids/specs/directory contains specs that were written as ADDED requirements for that specific change. These new baseline specs inopenspec/specs/document the current state including all the lowercase-project-ids functionality. Future changes will reference these baseline specs and mark their modifications as## MODIFIED Requirementsor## ADDED Requirements.Summary by cubic
Backports existing memex-core behavior into 15 baseline OpenSpec files under
openspec/specs/. These specs are the source of truth for current functionality and will anchor future changes (89 requirements, 161 scenarios).parseFrontmatter,parseMemoryFile),SkillIndexbuild/search, batching embeddings, sectioned memories.DEFAULT_CORE_CONFIG, guardedresolveCoreConfig, full type surface (skills, scoring, telemetry, paths).Written for commit fb3d24f. Summary will update on new commits.