sdd-full 4.8.0 → 4.8.2

package/skills/flutter-skills/tool/dart_skills_lint/.agents/skills/test-driven-development/testing-anti-patterns.md

@@ -1,299 +0,0 @@
-# Testing Anti-Patterns
-
-**Load this reference when:** writing or changing tests, adding mocks, or tempted to add test-only methods to production code.
-
-## Overview
-
-Tests must verify real behavior, not mock behavior. Mocks are a means to isolate, not the thing being tested.
-
-**Core principle:** Test what the code does, not what the mocks do.
-
-**Following strict TDD prevents these anti-patterns.**
-
-## The Iron Laws
-
-```
-1. NEVER test mock behavior
-2. NEVER add test-only methods to production classes
-3. NEVER mock without understanding dependencies
-```
-
-## Anti-Pattern 1: Testing Mock Behavior
-
-**The violation:**
-```typescript
-// ❌ BAD: Testing that the mock exists
-test('renders sidebar', () => {
-  render(<Page />);
-  expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
-});
-```
-
-**Why this is wrong:**
-- You're verifying the mock works, not that the component works
-- Test passes when mock is present, fails when it's not
-- Tells you nothing about real behavior
-
-**your human partner's correction:** "Are we testing the behavior of a mock?"
-
-**The fix:**
-```typescript
-// ✅ GOOD: Test real component or don't mock it
-test('renders sidebar', () => {
-  render(<Page />);  // Don't mock sidebar
-  expect(screen.getByRole('navigation')).toBeInTheDocument();
-});
-
-// OR if sidebar must be mocked for isolation:
-// Don't assert on the mock - test Page's behavior with sidebar present
-```
-
-### Gate Function
-
-```
-BEFORE asserting on any mock element:
-  Ask: "Am I testing real component behavior or just mock existence?"
-
-  IF testing mock existence:
-    STOP - Delete the assertion or unmock the component
-
-  Test real behavior instead
-```
-
-## Anti-Pattern 2: Test-Only Methods in Production
-
-**The violation:**
-```typescript
-// ❌ BAD: destroy() only used in tests
-class Session {
-  async destroy() {  // Looks like production API!
-    await this._workspaceManager?.destroyWorkspace(this.id);
-    // ... cleanup
-  }
-}
-
-// In tests
-afterEach(() => session.destroy());
-```
-
-**Why this is wrong:**
-- Production class polluted with test-only code
-- Dangerous if accidentally called in production
-- Violates YAGNI and separation of concerns
-- Confuses object lifecycle with entity lifecycle
-
-**The fix:**
-```typescript
-// ✅ GOOD: Test utilities handle test cleanup
-// Session has no destroy() - it's stateless in production
-
-// In test-utils/
-export async function cleanupSession(session: Session) {
-  const workspace = session.getWorkspaceInfo();
-  if (workspace) {
-    await workspaceManager.destroyWorkspace(workspace.id);
-  }
-}
-
-// In tests
-afterEach(() => cleanupSession(session));
-```
-
-### Gate Function
-
-```
-BEFORE adding any method to production class:
-  Ask: "Is this only used by tests?"
-
-  IF yes:
-    STOP - Don't add it
-    Put it in test utilities instead
-
-  Ask: "Does this class own this resource's lifecycle?"
-
-  IF no:
-    STOP - Wrong class for this method
-```
-
-## Anti-Pattern 3: Mocking Without Understanding
-
-**The violation:**
-```typescript
-// ❌ BAD: Mock breaks test logic
-test('detects duplicate server', () => {
-  // Mock prevents config write that test depends on!
-  vi.mock('ToolCatalog', () => ({
-    discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
-  }));
-
-  await addServer(config);
-  await addServer(config);  // Should throw - but won't!
-});
-```
-
-**Why this is wrong:**
-- Mocked method had side effect test depended on (writing config)
-- Over-mocking to "be safe" breaks actual behavior
-- Test passes for wrong reason or fails mysteriously
-
-**The fix:**
-```typescript
-// ✅ GOOD: Mock at correct level
-test('detects duplicate server', () => {
-  // Mock the slow part, preserve behavior test needs
-  vi.mock('MCPServerManager'); // Just mock slow server startup
-
-  await addServer(config);  // Config written
-  await addServer(config);  // Duplicate detected ✓
-});
-```
-
-### Gate Function
-
-```
-BEFORE mocking any method:
-  STOP - Don't mock yet
-
-  1. Ask: "What side effects does the real method have?"
-  2. Ask: "Does this test depend on any of those side effects?"
-  3. Ask: "Do I fully understand what this test needs?"
-
-  IF depends on side effects:
-    Mock at lower level (the actual slow/external operation)
-    OR use test doubles that preserve necessary behavior
-    NOT the high-level method the test depends on
-
-  IF unsure what test depends on:
-    Run test with real implementation FIRST
-    Observe what actually needs to happen
-    THEN add minimal mocking at the right level
-
-  Red flags:
-    - "I'll mock this to be safe"
-    - "This might be slow, better mock it"
-    - Mocking without understanding the dependency chain
-```
-
-## Anti-Pattern 4: Incomplete Mocks
-
-**The violation:**
-```typescript
-// ❌ BAD: Partial mock - only fields you think you need
-const mockResponse = {
-  status: 'success',
-  data: { userId: '123', name: 'Alice' }
-  // Missing: metadata that downstream code uses
-};
-
-// Later: breaks when code accesses response.metadata.requestId
-```
-
-**Why this is wrong:**
-- **Partial mocks hide structural assumptions** - You only mocked fields you know about
-- **Downstream code may depend on fields you didn't include** - Silent failures
-- **Tests pass but integration fails** - Mock incomplete, real API complete
-- **False confidence** - Test proves nothing about real behavior
-
-**The Iron Rule:** Mock the COMPLETE data structure as it exists in reality, not just fields your immediate test uses.
-
-**The fix:**
-```typescript
-// ✅ GOOD: Mirror real API completeness
-const mockResponse = {
-  status: 'success',
-  data: { userId: '123', name: 'Alice' },
-  metadata: { requestId: 'req-789', timestamp: 1234567890 }
-  // All fields real API returns
-};
-```
-
-### Gate Function
-
-```
-BEFORE creating mock responses:
-  Check: "What fields does the real API response contain?"
-
-  Actions:
-    1. Examine actual API response from docs/examples
-    2. Include ALL fields system might consume downstream
-    3. Verify mock matches real response schema completely
-
-  Critical:
-    If you're creating a mock, you must understand the ENTIRE structure
-    Partial mocks fail silently when code depends on omitted fields
-
-  If uncertain: Include all documented fields
-```
-
-## Anti-Pattern 5: Integration Tests as Afterthought
-
-**The violation:**
-```
-✅ Implementation complete
-❌ No tests written
-"Ready for testing"
-```
-
-**Why this is wrong:**
-- Testing is part of implementation, not optional follow-up
-- TDD would have caught this
-- Can't claim complete without tests
-
-**The fix:**
-```
-TDD cycle:
-1. Write failing test
-2. Implement to pass
-3. Refactor
-4. THEN claim complete
-```
-
-## When Mocks Become Too Complex
-
-**Warning signs:**
-- Mock setup longer than test logic
-- Mocking everything to make test pass
-- Mocks missing methods real components have
-- Test breaks when mock changes
-
-**your human partner's question:** "Do we need to be using a mock here?"
-
-**Consider:** Integration tests with real components often simpler than complex mocks
-
-## TDD Prevents These Anti-Patterns
-
-**Why TDD helps:**
-1. **Write test first** → Forces you to think about what you're actually testing
-2. **Watch it fail** → Confirms test tests real behavior, not mocks
-3. **Minimal implementation** → No test-only methods creep in
-4. **Real dependencies** → You see what the test actually needs before mocking
-
-**If you're testing mock behavior, you violated TDD** - you added mocks without watching test fail against real code first.
-
-## Quick Reference
-
-| Anti-Pattern | Fix |
-|--------------|-----|
-| Assert on mock elements | Test real component or unmock it |
-| Test-only methods in production | Move to test utilities |
-| Mock without understanding | Understand dependencies first, mock minimally |
-| Incomplete mocks | Mirror real API completely |
-| Tests as afterthought | TDD - tests first |
-| Over-complex mocks | Consider integration tests |
-
-## Red Flags
-
-- Assertion checks for `*-mock` test IDs
-- Methods only called in test files
-- Mock setup is >50% of test
-- Test fails when you remove mock
-- Can't explain why mock is needed
-- Mocking "just to be safe"
-
-## The Bottom Line
-
-**Mocks are tools to isolate, not things to test.**
-
-If TDD reveals you're testing mock behavior, you've gone wrong.
-
-Fix: Test real behavior or question why you're mocking at all.

package/skills/flutter-skills/tool/dart_skills_lint/AUTHORS

@@ -1,7 +0,0 @@
-# Below is a list of people and organizations that have contributed
-# to the project. Names should be added to the list like so:
-#
-#   Name/Organization <email address>
-
-Google Inc.
-Reid Baker reidbaker@google.com

package/skills/flutter-skills/tool/dart_skills_lint/CHANGELOG.md

@@ -1,12 +0,0 @@
-## 0.2.0
-
-- Refactored validator to a pluggable rule-based architecture.
-- Added support for custom rules via `SkillRule`.
-- Added runtime assertion for duplicate rule names.
-- Added warning when a rule emits an error with severity different from its definition.
-- Updated `README.md` with custom rules documentation.
-- **Breaking Change**: Enabling a rule via CLI flag now sets its severity to `error` instead of `warning`.
-
-## 0.1.0
-
-- Initial version.

package/skills/flutter-skills/tool/dart_skills_lint/CONTRIBUTING.md

@@ -1,51 +0,0 @@
-# How to Contribute
-
-We'd love to accept your patches and contributions to this project. There are
-just a few small guidelines you need to follow.
-
-## Contributor License Agreement
-
-Contributions to this project must be accompanied by a Contributor License
-Agreement (CLA). You (or your employer) retain the copyright to your
-contribution; this simply gives us permission to use and redistribute your
-contributions as part of the project. Head over to
-<https://cla.developers.google.com/> to see your current agreements on file or
-to sign a new one.
-
-You generally only need to submit a CLA once, so if you've already submitted one
-(even if it was for a different project), you probably don't need to do it
-again.
-
-## Code Reviews
-
-All submissions, including submissions by project members, require review. We
-use GitHub pull requests for this purpose. Consult
-[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
-information on using pull requests.
-
-## Coding style
-
-The Dart source code in this repo follows the:
-
-  * [Dart style guide](https://dart.dev/guides/language/effective-dart/style)
-
-You should familiarize yourself with those guidelines.
-
-## File headers
-
-All files in the Dart project must start with the following header; if you add a
-new file please also add this. The year should be a single number stating the
-year the file was created (don't use a range like "2011-2012"). Additionally, if
-you edit an existing file, you shouldn't update the year.
-
-    // Copyright (c) 2026, the Dart project authors.  Please see the AUTHORS file
-    // for details. All rights reserved. Use of this source code is governed by a
-    // BSD-style license that can be found in the LICENSE file.
-
-## Community Guidelines
-
-This project follows
-[Google's Open Source Community Guidelines](https://opensource.google/conduct/).
-
-We pledge to maintain an open and welcoming environment. For details, see our
-[code of conduct](https://dart.dev/code-of-conduct).

package/skills/flutter-skills/tool/dart_skills_lint/LICENSE

@@ -1,27 +0,0 @@
-Copyright 2026, the Dart project authors.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are
-met:
-
-    * Redistributions of source code must retain the above copyright
-      notice, this list of conditions and the following disclaimer.
-    * Redistributions in binary form must reproduce the above
-      copyright notice, this list of conditions and the following
-      disclaimer in the documentation and/or other materials provided
-      with the distribution.
-    * Neither the name of Google LLC nor the names of its
-      contributors may be used to endorse or promote products derived
-      from this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/skills/flutter-skills/tool/dart_skills_lint/README.md

@@ -1,203 +0,0 @@
-# dart_skills_lint
-
-A static analysis linter for Agent Skills to ensure they meet the specification in presubmit checks. This project is a Dart package and can be run as a CLI tool to validate your skills directory before committing.
-
-## Table of Contents
-- [Overview](#overview)
-- [Installation](#installation)
-- [Usage](#usage)
-- [Configuration](#configuration)
-- [Specification Validation](#specification-validation)
-- [Best Practices](#best-practices)
-
-## Overview
-
-An **Agent Skill** is a portable, self-contained directory that extends an AI agent's capabilities. Pre-submit linting ensures that your skill definitions are valid and ready for consumption by agent platforms.
-
-`dart_skills_lint` validates:
-- Presence of mandatory `SKILL.md` file.
-- YAML frontmatter constraints (naming, length, etc.).
-- Directory structure (flat, no deep nesting).
-- Relative path integrity.
-
-For a full definition of the skill standard, see the [Agent Skills Specification](documentation/knowledge/SPECIFICATION.md).
-
-## Installation
-
-Add `dart_skills_lint` to your Dart project or activate it globally.
-
-### 1. As a project dependency
-Add it to your `pubspec.yaml` (once published on pub.dev):
-```yaml
-dev_dependencies:
-  dart_skills_lint: ^0.2.0
-```
-Then run:
-```bash
-dart pub get
-```
-
-### 2. Globally activated
-If you want to use it across multiple projects without adding it to each `pubspec.yaml`:
-```bash
-dart pub global activate dart_skills_lint
-```
-
-## Usage
-
-There are three ways to interact with `dart_skills_lint`:
-
-### 1. As a Command Line Tool with Arguments
-Run the linter against your skills or root skills directories by passing arguments.
-
-```bash
-dart run dart_skills_lint --skills-directory ./path/to/skills-root
-```
-
-Multiple root directories can be specified:
-```bash
-dart run dart_skills_lint --skills-directory ./path/to/root-a --skills-directory ./path/to/root-b
-```
-
-Validate Individual Skills directly using `--skill` or `-s`:
-```bash
-dart run dart_skills_lint --skill ./path/to/my-single-skill
-```
-
-If no directory is specified, it automatically checks `.claude/skills` and `.agents/skills` relative to your workspace root.
-
-### Flags
-- `-d`, `--skills-directory`: Specifies a root directory containing sub-folders of skills to validate. Can be passed multiple times. Can use home tilde expansion (ex: `~/.agents/skills`).
-- `-s`, `--skill`: Specifies an individual skill directory to validate directly. Can be passed multiple times.
-- `-q`, `--quiet`: Hide non-error validation output.
-- `-w`, `--print-warnings`: Enable printing of warning messages.
-- `--fast-fail`: Halt execution immediately on the error.
-- `--ignore-config`: Ignore the YAML configuration file entirely.
-- `--[no-]check-trailing-whitespace`: Enable/disable checking for trailing whitespace. (Disabled by default).
-- `--fix`: Preview fixes for failing lints (dry run).
-- `--fix-apply`: Apply fixes for failing lints.
-
-### 2. As a Command Line Tool with a YAML Configuration File
-You can configure the linter using a configuration file (defaulting to `dart_skills_lint.yaml` in the current directory).
-
-Create `dart_skills_lint.yaml` in the root of your repository:
-
-```yaml
-# dart_skills_lint.yaml
-dart_skills_lint:
-  rules:
-    check-relative-paths: error
-    check-absolute-paths: error
-  directories:
-    - path: "~/.agents/skills"
-      ignore_file: "~/.agents/skills/ignore.json"
-```
-
-Then you can simply run:
-```bash
-dart run dart_skills_lint
-```
-
-### 3. As Dart Test Code
-You can integrate the linter into your automated tests by importing the package and calling `validateSkills`. This allows you to enforce skill validity as part of your standard test suite.
-
-Example `test/lint_skills_test.dart`:
-```dart
-import 'package:dart_skills_lint/dart_skills_lint.dart';
-import 'package:test/test.dart';
-
-void main() {
-  test('Run skills linter', () async {
-    final config = Configuration(
-      directoryConfigs: [
-        DirectoryConfig(
-          path: '../../skills',
-          rules: {},
-          ignoreFile: '.agents/skills/flutter_skills_ignore.json',
-        ),
-      ],
-    );
-
-    await validateSkills(
-      skillDirPaths: ['../../skills'],
-      resolvedRules: {
-        'check-relative-paths': AnalysisSeverity.error,
-        'check-absolute-paths': AnalysisSeverity.error,
-      },
-      config: config,
-    );
-  });
-}
-```
-
-You can also use `Validator` and `ValidationResult` directly if you need to inspect the errors programmatically.
-
-### Custom Rules
-
-You can author custom rules by extending the `SkillRule` class and passing them to `validateSkills` or the `Validator` constructor.
-
-Example custom rule:
-```dart
-import 'package:dart_skills_lint/dart_skills_lint.dart';
-
-class MyCustomRule extends SkillRule {
-  @override
-  final String name = 'my-custom-rule';
-
-  @override
-  final AnalysisSeverity severity = AnalysisSeverity.warning;
-
-  @override
-  Future<List<ValidationError>> validate(SkillContext context) async {
-    final errors = <ValidationError>[];
-    final yaml = context.parsedYaml;
-    if (yaml == null) return errors;
-
-    if (yaml['metadata']?['deprecated'] == true) {
-      errors.add(ValidationError(
-        ruleId: name,
-        severity: severity,
-        file: 'SKILL.md',
-        message: 'This skill is marked as deprecated.',
-      ));
-    }
-    return errors;
-  }
-}
-```
-
-Then use it in your test:
-```dart
-    await validateSkills(
-      skillDirPaths: ['../../skills'],
-      customRules: [MyCustomRule()],
-    );
-```
-
-## Specification Validation
-
-The linter checks against the criteria defined in `documentation/knowledge/SPECIFICATION.md` (Section 5.1). Key checks include:
-
-### 1. Directory and File Structure
-- Path existence and directory verification.
-- Mandatory `SKILL.md` file at the root.
-- Directories starting with a dot `.` (e.g., `.dart_tool`) are ignored when scanning for skills.
-
-### 2. Metadata (YAML Frontmatter)
-- Valid YAML syntax.
-- Allowed fields: `name`, `description`, `license`, `allowed-tools`, `metadata`, `compatibility`, `category`, `tags`, `version`, `eval_task`.
-- Required fields: `name` and `description`.
-
-### 3. Field Specific Constraints
-- **Skill Name (`name`)**: Max 64 characters, lowercase alphanumeric and hyphens only, no leading/trailing/consecutive hyphens. **Must match the parent directory name.**
-- **Description (`description`)**: Max 1024 characters.
-- **Compatibility (`compatibility`)**: Max 500 characters.
-
-### 4. Content Constraints
-- **Trailing Whitespace**: Lines in `SKILL.md` should not have trailing whitespace. Exactly 2 spaces at the end of a line are allowed to support Markdown hard line breaks, per the [CommonMark Spec](https://spec.commonmark.org/0.31.2/#hard-line-breaks).
-- **Path Constraints**: Checks that **inline** Markdown links do not use absolute paths to enforce portability. Can optionally be configured to check that relative paths point to valid, existing files (disabled by default). *Note: This rule only supports inline Markdown links and does not detect HTML or reference-style links.*
-
-## Contributing
-
-Contributions are welcome! Please ensure that any PRs pass the linter themselves and align with the `documentation/knowledge/SPECIFICATION.md`.
-