feat: implement task filtering by tags and names

[thalesraymond]

Implemented the add-task-filtering pending change specification.

The changes involve introducing task tags and robust filtering mechanisms via TaskFilterConfig. Users can dynamically include or exclude tasks by names or tags, and optionally resolve their dependent closures natively inside TaskRunner.

Comprehensive test suites were added, ensuring precise validation behavior. Pre-commit hooks including linting, building, and 100% code coverage tests passed. The proposal folders were then archived into openspec/changes/archive/.

---

PR created automatically by Jules for task 3023652389587345650 started by @thalesraymond

[google-labs-jules]

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

New to Jules? Learn more at jules.google/docs.

---

For security, I will only act on instructions from the user who triggered this task.

[sonarqubecloud]

Quality Gate passed

Issues
6 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[gemini-code-assist]

Code Review

This pull request introduces task filtering capabilities to the TaskRunner, allowing users to include or exclude tasks based on names and tags. It includes a new TaskFilterConfig interface, updates to TaskStep to support tags, and a filterTasks utility for processing these criteria. Feedback was provided to optimize the filterTasks implementation by using Set objects for O(1) lookups instead of repeated array iterations, which improves performance for large task sets.

[gemini-code-assist]

The current implementation uses multiple array lookups (.includes()) and iterations (.some()) inside loops, leading to O(N*M) complexity. Converting filter criteria to Set objects provides O(1) lookups, which is significantly more efficient for larger task sets. Additionally, the inclusion and dependency resolution logic can be simplified for better maintainability and performance by avoiding redundant checks and sets.

  const includeNames = new Set(config.includeNames ?? []);
  const includeTags = new Set(config.includeTags ?? []);
  const excludeNames = new Set(config.excludeNames ?? []);
  const excludeTags = new Set(config.excludeTags ?? []);

  const stepMap = new Map(steps.map((step) => [step.name, step]));
  const initialMatches = new Set<string>();

  const hasIncludeCriteria = includeNames.size > 0 || includeTags.size > 0;

  for (const step of steps) {
    let included = !hasIncludeCriteria;

    if (hasIncludeCriteria) {
      const nameMatch = includeNames.has(step.name);
      const tagMatch = step.tags?.some((tag) => includeTags.has(tag)) ?? false;
      included = nameMatch || tagMatch;
    }

    if (included && (excludeNames.has(step.name) || (step.tags?.some((tag) => excludeTags.has(tag)) ?? false))) {
      included = false;
    }

    if (included) {
      initialMatches.add(step.name);
    }
  }

  if (config.includeDependencies) {
    const queue = Array.from(initialMatches);

    while (queue.length > 0) {
      const currentName = queue.shift()!;
      const currentStep = stepMap.get(currentName);

      if (currentStep?.dependencies) {
        for (const dep of currentStep.dependencies) {
          if (initialMatches.has(dep)) continue;

          const depStep = stepMap.get(dep);
          const isExcluded = excludeNames.has(dep) || 
            (depStep?.tags?.some((tag) => excludeTags.has(tag)) ?? false);

          if (!isExcluded) {
            initialMatches.add(dep);
            queue.push(dep);
          }
        }
      }
    }
  }

References

1. When frequent lookups of items by a specific key are required, use a Map (or dictionary/hash table) to store the items, indexed by that key, to ensure O(1) access time.