feat(sdd): implement spec-to-tracker bridge and root tracker id generation#24072
feat(sdd): implement spec-to-tracker bridge and root tracker id generation#24072moisgobg wants to merge 3 commits intofeat/builtin-conductorfrom
Conversation
…sure project precedence - Add 'tracker' property to ExtensionConfig to allow extensions to specify task tracking directories. - Fix extension loading to pass tracker configuration from extensions. - Implement project-level precedence for tracker directory over extension defaults. - Add comprehensive tests for tracker directory resolution and precedence.
|
Hi @moisgobg, thank you so much for your contribution to Gemini CLI! We really appreciate the time and effort you've put into this. We're making some updates to our contribution process to improve how we track and review changes. Please take a moment to review our recent discussion post: Improving Our Contribution Process & Introducing New Guidelines. Key Update: Starting January 26, 2026, the Gemini CLI project will require all pull requests to be associated with an existing issue. Any pull requests not linked to an issue by that date will be automatically closed. Thank you for your understanding and for being a part of our community! |
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request establishes a foundational bridge between the SDD extension's specification system and the task tracking infrastructure. By automating the creation of a Root Tracker Epic during spec initialization, it ensures a consistent 1:1 relationship between project intent and execution state, while providing necessary configuration flexibility and security policies for tracker operations. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. Footnotes
|
moisgobg
added
area/core
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces support for a configurable task tracker directory, allowing users and extensions to specify where tracking data is stored. It includes updates to the configuration schema, extension manager, and storage logic, along with corresponding unit tests. Additionally, the SDD (Software Design Document) built-in extension is updated to utilize the tracker for creating root tasks and managing spec metadata. A review comment suggests refactoring the path resolution logic in the storage module to eliminate code duplication and ensure consistent security checks for path traversal.
Note: Security Review did not run due to the size of the PR.
| getTrackerDir(): string { | ||
| if (this.customTrackerDir) { | ||
| const resolvedPath = path.resolve( | ||
| this.getProjectRoot(), | ||
| this.customTrackerDir, | ||
| ); | ||
| const realProjectRoot = resolveToRealPath(this.getProjectRoot()); | ||
| const realResolvedPath = resolveToRealPath(resolvedPath); | ||
|
|
||
| if (!isSubpath(realProjectRoot, realResolvedPath)) { | ||
| throw new Error( | ||
| `Custom tracker directory '${this.customTrackerDir}' resolves to '${realResolvedPath}', which is outside the project root '${realProjectRoot}'.`, | ||
| ); | ||
| } | ||
|
|
||
| return resolvedPath; | ||
| } | ||
| return this.getProjectTempTrackerDir(); | ||
| } |
There was a problem hiding this comment.
The logic inside getTrackerDir is nearly identical to the existing getPlansDir method. This duplication increases maintenance overhead and the risk of introducing inconsistencies if one is updated and the other is not. Since this logic includes security checks (path traversal prevention), it's particularly important to keep it DRY (Don't Repeat Yourself).
Consider refactoring this logic into a private helper method. This new method can then be used by both getTrackerDir and getPlansDir.
For example:
private _resolveCustomDir(
customDir: string | undefined,
dirTypeName: string,
fallbackPath: string
): string {
if (customDir) {
const resolvedPath = path.resolve(this.getProjectRoot(), customDir);
const realProjectRoot = resolveToRealPath(this.getProjectRoot());
const realResolvedPath = resolveToRealPath(resolvedPath);
if (!isSubpath(realProjectRoot, realResolvedPath)) {
throw new Error(
`Custom ${dirTypeName} directory '${customDir}' resolves to '${realResolvedPath}', which is outside the project root '${realProjectRoot}'.`
);
}
return resolvedPath;
}
return fallbackPath;
}Then getTrackerDir would become:
getTrackerDir(): string {
return this._resolveCustomDir(
this.customTrackerDir,
'tracker',
this.getProjectTempTrackerDir()
);
}References
- Sanitize user-provided file paths used in file system operations to prevent path traversal vulnerabilities.
- Ensure consistent path resolution by using a single, robust function (e.g., resolveToRealPath) for all related path validations.
- Functionally similar sections should be located in the same spot for consistency, as security or other concerns for one likely apply to both.
- Utility functions that perform file system operations should validate their path inputs internally to prevent path traversal vulnerabilities.
2 participants
Summary
This PR implements the foundational Spec-to-Tracker bridge for the SDD extension. It configures a dedicated tracker directory for the extension and updates the
createandsetupcommands to automatically generate a Root Tracker Epic for each new spec, establishing the 1:1 relationship between intent (spec) and execution state (tracker).Details
gemini-extension.jsonto configure.gemini/trackeras the specific tracker directory for the SDD extension.tracker_create_task,tracker_update_task) to be called in Plan Mode viasdd.tomlwith anask_userpolicy to ensure safety./spec:setupand/spec:createworkflows in their respective TOML definitions to:tracker_create_task(with typeepic) upon spec approval.root_tracker_idinside the spec'smetadata.json.Related Issues
Resolves #23802
How to Validate
npm run build -w @google/gemini-cli-core.npm start)./spec:create "Test the tracker integration".tracker_create_task.metadata.jsonin.gemini/specs/specs/<spec_id>/and ensure theroot_tracker_idis present..gemini/tracker/.Pre-Merge Checklist