{"id":"0935c688-2a34-4b1b-ace4-57e8b06deebd","entityType":"agent","slug":"clawhub-jingzhao-l-iterate-skill","name":"Iterate","canonicalUrl":"https://www.xpersona.co/agent/clawhub-jingzhao-l-iterate-skill","canonicalPath":"/agent/clawhub-jingzhao-l-iterate-skill","generatedAt":"2026-10-09T16:34:02.360Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T13:00:16.526Z","emptyReason":null},"description":"Fully automated multi-round code iteration with configurable N-dimension parallel review, onboarding/personalization, and a cross-assistant installer/update system with mandatory SHA256 checksum verification. v3.0 adds a dual-mode (the original iterate mode plus a defensive-programming mode via /iterate defensive) that performs normal incremental coding tasks with defensive discipline end-to-end.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.6K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s1722v1f08paw6feta6f0f11t18awbn2:iterate-skill","sourceUrl":"https://clawhub.ai/jingzhao-l/iterate-skill","homepage":"https://clawhub.ai/jingzhao-l/skills/iterate-skill","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/jingzhao-l/iterate-skill","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/jingzhao-l/skills/iterate-skill","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":68,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Iterate technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T13:00:16.526Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T13:00:16.526Z","emptyReason":null},"stars":null,"forks":null,"downloads":2605,"packageName":null,"latestVersion":"3.4.4","tractionLabel":"2.6K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T13:00:16.525Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T13:00:16.526Z","lastCrawledAt":"2026-10-09T13:00:16.525Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T13:00:16.526Z","lastVerifiedAt":null,"highlights":[{"version":"3.4.4","createdAt":"2026-10-04T02:10:58.627Z","changelog":"**Changelog for iterate-skill v3.4.4** - Added \"kernel\" module with schema definitions, source files, tests, and data fixtures for review evidence and config validation. - Expanded test coverage with new test scripts and sample data for validation and roundtrip checks. - Updated CLI, config, and review logic for improved modularity and maintainability. - Improved documentation (README, CONTRIBUTING, SKILL.md) for clearer onboarding and usage guidance. - Internal scripts updated for publishing, validation, and automation workflows. - Removed obsolete files (e.g., skill-card.md) as part of project cleanup.","fileCount":112,"zipByteSize":710596},{"version":"3.4.2","createdAt":"2026-09-18T00:06:35.101Z","changelog":"## iterate-skill v3.4.2 - Improvements and fixes to CLI modules and onboarding/personalization logic. - npm installer scripts updated and test coverage refined. - Documentation files (CHANGELOG.md, SKILL.md, RELEASE.md) updated for clarity and latest features. - One obsolete documentation file (skill-card.md) removed. - Various tests updated for sync with current behavior.","fileCount":82,"zipByteSize":621900},{"version":"3.4.1","createdAt":"2026-09-16T12:45:47.708Z","changelog":"Version 3.4.1 - Updated documentation and markdown files for clarity and improved detail. - Removed the obsolete skill-card.md file. - Minor internal code and test adjustments in CLI and updater modules. - Maintained all previous features and dual-mode (iterate/defensive) functionality.","fileCount":82,"zipByteSize":611980},{"version":"3.4.0","createdAt":"2026-09-15T23:14:38.064Z","changelog":"**v3.4.0 introduces an updater utility and related improvements.** - Added `updater.py` to support skill updating functionality. - Introduced new tests for the updater (`test_updater.py`, `test_updater_sync.py`). - Updated CLI components to integrate with the updater module. - Removed obsolete `skill-card.md` file. - Updated metadata and documentation for the new version.","fileCount":82,"zipByteSize":605622},{"version":"3.3.1","createdAt":"2026-09-14T10:12:51.792Z","changelog":"iterate-skill 3.3.1 - Updated documentation in SKILL.md for greater clarity; content reorganized, no user-facing logic changes. - Removed obsolete skill-card.md. - Minor schema/config/metadata updates to align with ecosystem standards. - General cleanup of auxiliary and test files.","fileCount":79,"zipByteSize":584191},{"version":"3.3.0","createdAt":"2026-09-13T07:47:53.240Z","changelog":"**v3.3.0 of iterate-skill** - Refactored and updated handling of configuration and onboarding logic. - Improved documentation files (README.md, SKILL.md, DESIGN-iterate-plugin.md) for clarity and completeness. - Enhanced defensive-programming mode and review-only (dry-run) workflows. - Expanded and reorganized tests covering config, doctor, guard, install script, onboarding, and publish flows. - Removed legacy file `skill-card.md`.","fileCount":79,"zipByteSize":582569},{"version":"3.2.3","createdAt":"2026-09-10T14:28:51.646Z","changelog":"## iterate-skill 3.2.3 - Documentation updates: SKILL.md and other markdown files revised for clarity and completeness. - Metadata and manifest adjustments to reflect latest features and parameter details. - Old/deprecated file skill-card.md removed. - Dependency declarations updated in pyproject.toml and package.json. - Updated badges, release, and changelog metadata for latest version.","fileCount":79,"zipByteSize":568994},{"version":"3.2.2","createdAt":"2026-09-09T15:04:16.845Z","changelog":"iterate-skill v3.2.2 - Updated documentation files (SKILL.md, DESIGN-iterate-plugin.md, RELEASE.md, CHANGELOG.md). - Minor CLI and doctor module improvements. - Updated npm and Python project config files. - Enhanced and expanded test coverage. - Removed deprecated file: skill-card.md.","fileCount":79,"zipByteSize":568070}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s1722v1f08paw6feta6f0f11t18awbn2:iterate-skill","setupComplexity":"medium","setupSteps":["Install using `clawhub skill install s1722v1f08paw6feta6f0f11t18awbn2:iterate-skill` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/jingzhao-l/iterate-skill before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jingzhao-l-iterate-skill/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jingzhao-l-iterate-skill/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jingzhao-l-iterate-skill/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-jingzhao-l-iterate-skill/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-jingzhao-l-iterate-skill/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-jingzhao-l-iterate-skill/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T16:34:02.356Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jingzhao-l-iterate-skill/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jingzhao-l-iterate-skill/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jingzhao-l-iterate-skill/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jingzhao-l-iterate-skill/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T13:00:16.526Z","emptyReason":null},"readme":"Skill: Iterate\n\nOwner: jingzhao-l\n\nSummary: Fully automated multi-round code iteration with configurable N-dimension parallel review, onboarding/personalization, and a cross-assistant installer/update system with mandatory SHA256 checksum verification. v3.0 adds a dual-mode (the original iterate mode plus a defensive-programming mode via /iterate defensive) that performs normal incremental coding tasks with defensive discipline end-to-end.\n\nTags: latest:3.4.4\n\nVersion history:\n\nv3.4.4 | 2026-10-04T02:10:58.627Z | auto\n\n**Changelog for iterate-skill v3.4.4**\n\n- Added \"kernel\" module with schema definitions, source files, tests, and data fixtures for review evidence and config validation.\n- Expanded test coverage with new test scripts and sample data for validation and roundtrip checks.\n- Updated CLI, config, and review logic for improved modularity and maintainability.\n- Improved documentation (README, CONTRIBUTING, SKILL.md) for clearer onboarding and usage guidance.\n- Internal scripts updated for publishing, validation, and automation workflows.\n- Removed obsolete files (e.g., skill-card.md) as part of project cleanup.\n\nv3.4.2 | 2026-09-18T00:06:35.101Z | auto\n\n## iterate-skill v3.4.2\n\n- Improvements and fixes to CLI modules and onboarding/personalization logic.\n- npm installer scripts updated and test coverage refined.\n- Documentation files (CHANGELOG.md, SKILL.md, RELEASE.md) updated for clarity and latest features.\n- One obsolete documentation file (skill-card.md) removed.\n- Various tests updated for sync with current behavior.\n\nv3.4.1 | 2026-09-16T12:45:47.708Z | auto\n\nVersion 3.4.1\n\n- Updated documentation and markdown files for clarity and improved detail.\n- Removed the obsolete skill-card.md file.\n- Minor internal code and test adjustments in CLI and updater modules.\n- Maintained all previous features and dual-mode (iterate/defensive) functionality.\n\nv3.4.0 | 2026-09-15T23:14:38.064Z | auto\n\n**v3.4.0 introduces an updater utility and related improvements.**\n\n- Added `updater.py` to support skill updating functionality.\n- Introduced new tests for the updater (`test_updater.py`, `test_updater_sync.py`).\n- Updated CLI components to integrate with the updater module.\n- Removed obsolete `skill-card.md` file.\n- Updated metadata and documentation for the new version.\n\nv3.3.1 | 2026-09-14T10:12:51.792Z | auto\n\niterate-skill 3.3.1\n\n- Updated documentation in SKILL.md for greater clarity; content reorganized, no user-facing logic changes.\n- Removed obsolete skill-card.md.\n- Minor schema/config/metadata updates to align with ecosystem standards.\n- General cleanup of auxiliary and test files.\n\nv3.3.0 | 2026-09-13T07:47:53.240Z | auto\n\n**v3.3.0 of iterate-skill**\n\n- Refactored and updated handling of configuration and onboarding logic.\n- Improved documentation files (README.md, SKILL.md, DESIGN-iterate-plugin.md) for clarity and completeness.\n- Enhanced defensive-programming mode and review-only (dry-run) workflows.\n- Expanded and reorganized tests covering config, doctor, guard, install script, onboarding, and publish flows.\n- Removed legacy file `skill-card.md`.\n\nv3.2.3 | 2026-09-10T14:28:51.646Z | auto\n\n## iterate-skill 3.2.3\n\n- Documentation updates: SKILL.md and other markdown files revised for clarity and completeness.\n- Metadata and manifest adjustments to reflect latest features and parameter details.\n- Old/deprecated file skill-card.md removed.\n- Dependency declarations updated in pyproject.toml and package.json.\n- Updated badges, release, and changelog metadata for latest version.\n\nv3.2.2 | 2026-09-09T15:04:16.845Z | auto\n\niterate-skill v3.2.2\n\n- Updated documentation files (SKILL.md, DESIGN-iterate-plugin.md, RELEASE.md, CHANGELOG.md).\n- Minor CLI and doctor module improvements.\n- Updated npm and Python project config files.\n- Enhanced and expanded test coverage.\n- Removed deprecated file: skill-card.md.\n\nv3.2.1 | 2026-09-07T12:50:54.115Z | auto\n\nVersion 3.2.1\n\n- Refactored and updated core CLI and plugin logic across multiple files.\n- Improved configuration, onboarding, and validation workflows.\n- Enhanced documentation and guidance in SKILL.md and supporting docs.\n- Removed deprecated skill-card.md.\n- General maintenance: test coverage, badges, and release metadata updated.\n\nv3.2.0 | 2026-09-06T03:05:45.958Z | auto\n\nVersion 3.2.0\n\n- Major refactors and improvements across 29 files, including CLI modules, onboarding, and review infrastructure.\n- Removed legacy file: skill-card.md.\n- Expanded and clarified documentation (README, SKILL.md) for multi-mode usage, onboarding, parameters, and review/reporting flows.\n- Improved test coverage, expanded test cases (for config, guard, onboarding, update badge, and refresh logic).\n- Enhanced install and badge update scripts for more robust automation.\n\nv3.1.0 | 2026-09-05T01:46:01.855Z | auto\n\n**Iterate Skill v3.1.0 — Feature Upgrade & Maintenance Release**\n\n- Expanded and documented CLI and module improvements across 17 files, with one deprecated file removed.\n- Updated documentation: CHANGELOG, README (including Chinese), RELEASE.md, and SKILL manifest.\n- Enhanced onboarding, personalization, and doctor tools for better user experience.\n- Improved code review and iteration logic, addressing edge cases and defensive programming workflow.\n- Refined testing suite with updates to test_doctor, test_drift_ignore, and test_onboarding.\n- Removed outdated skill-card.md as part of documentation cleanup.\n\nv3.0.1 | 2026-09-03T13:30:39.464Z | auto\n\n- `guard pre-check` now fails closed (exits with 1) if the project has been onboarded (`iterate.config.yaml` exists) but `validation.commands` is empty, ensuring defensive mode never gives a misleading \"clear to start\" without actual validation commands.\n- New projects (no config yet) still allow passing pre-check gracefully.\n- Added test coverage for release metadata.\n- Documentation updated to clarify new defensive fail-closed behavior.\n\nv3.0.0 | 2026-09-03T11:51:32.105Z | auto\n\n# iterate-skill v3.0.0\n\n**Summary:** \nv3.0.0 introduces dual-mode support: the classic multi-round code iteration and a new defensive-programming mode for end-to-end incremental coding tasks.\n\n- Adds a defensive-programming mode (`/iterate defensive `) for normal incremental coding tasks, enforcing defensive discipline (pre-check, minimal-step edits, post-check, and iterate convergence as delivery gate).\n- Maintains all original iterate multi-round code review/repair features (v2 abilities unchanged).\n- Updates manifest and documentation to explain dual-mode usage, parameters, and when each mode applies.\n- Implements logic, config, and test changes to support the new defensive mode alongside classic iteration.\n- Expands CLI, schema, and onboarding process to accommodate and document both modes.\n\nv2.12.0 | 2026-09-02T13:28:57.839Z | auto\n\n**Summary: Onboarding, CLI, and script system improved with backward-compatible enhancements.**\n\n- Major improvements to onboarding logic and multi-root project detection, especially for monorepos.\n- CLI and config command modules updated for better configuration and usability.\n- Install and publish scripts received significant enhancements for robustness and multi-assistant integration.\n- Test coverage expanded, including onboarding, install script, and publish flows.\n- Removed obsolete or redundant documentation files.\n\nv2.11.2 | 2026-09-01T13:51:04.120Z | auto\n\n**Minor update with test improvements and documentation cleanup.**\n\n- Added a new test for `publish_qoder.py` to improve coverage.\n- Updated multiple test files for consistency and enhancements.\n- Improved documentation in `SKILL.md`, `CHANGELOG.md`, and related files.\n- Removed outdated skill-card documentation.\n- Routine package and dependency version bumps.\n\nv2.11.1 | 2026-09-01T10:14:30.530Z | auto\n\n- Removed the obsolete skill-card.md file.\n- Updated internal documentation: revised CHANGELOG.md, RELEASE.md, and SKILL.md.\n- Adjusted configuration and manifest references in SKILL.md to match latest project conventions.\n- Updated package metadata in npm-installer/package.json and pyproject.toml.\n- Improved onboarding instructions and multi-project handling in SKILL.md.\n- Enhanced validation and testing scripts (scripts/validate.py, tests/test_validate.py).\n\nv2.11.0 | 2026-09-01T09:28:57.025Z | auto\n\n**Summary: Introduced a flexible dimension set system and improved dimension planning.**\n\n- Added support for dimension sets: dimension reviewers can now be grouped and selected via config or dynamically per review goal.\n- New: `/iterate` goal can be routed to a predefined or ad-hoc dimension set, recorded with bounded history.\n- Enhanced onboarding and validation for new dimension set workflows.\n- Refactored and updated internal config, CLI, and tests to support dynamic dimension set selection.\n- Removed legacy skill-card.md (deprecated).\n\nv2.10.0 | 2026-08-30T00:03:23.808Z | auto\n\n**iterate-skill 2.10.0**\n\n- Introduced new CLI command/configuration helpers (see added `iterate_cli/configcmd.py`).\n- Added a Chinese documentation file (`README.zh-CN.md`) for improved accessibility.\n- Added new scripts and tests, including publishing and configuration coverage.\n- Refined and updated main CLI modules with changes across core logic files.\n- Removed deprecated/legacy documentation (`skill-card.md`).\n\nv2.9.1 | 2026-08-26T23:51:39.152Z | auto\n\n**iterate-skill 2.9.1**\n\n- Improved and updated documentation in `SKILL.md`; descriptions and instructions clarified.\n- Updated sensitive file skip patterns to improve security filtering (added \"secrets/\" and reordered list).\n- Minor maintenance: removal of deprecated file `skill-card.md`.\n- Miscellaneous internal and documentation improvements across CLI and installer scripts.\n\nv2.9.0 | 2026-08-25T23:50:04.761Z | auto\n\n**2.9.0 is a significant update with broad changes to core files, docs, CLI logic, and onboarding.**\n\n- Updated onboarding logic and drift detection with improvements to configuration and manifest handling.\n- Refreshed and reorganized documentation, including major SKILL.md and README.md updates; removed obsolete files.\n- Enhanced CLI features and internal structure across multiple iterate_cli modules (init, cli, generator, personalize, refresh, scan, show, tui, wizard).\n- Updated npm installer logic and related tests for broader reliability.\n- Improved test coverage with changes to several test scripts.\n- Numerous config, badge, and workflow updates to streamline multi-round review, install/update, and parallel checking.\n\nv2.8.1 | 2026-08-23T14:13:49.212Z | auto\n\n**iterate-skill 2.8.1 — Maintenance update**\n\n- Updated documentation in SKILL.md, focusing on clarity and improved onboarding/drift-check guidance.\n- Removed legacy skill-card.md file.\n- Refreshed badges and download counters.\n- Minor improvements and cleanup across CLI scripts, onboarding, and testing.\n- No breaking changes.\n\nv2.8.0 | 2026-08-22T10:33:49.453Z | auto\n\n## iterate-skill 2.8.0\n\n- Improved drift ignore mechanism for onboarding: now supports a more flexible and robust ignore list in onboarding checks.\n- Refined onboarding and drift detection logic for project manifests.\n- CLI enhancements and cleanup, removing deprecated or redundant files (e.g., removed `skill-card.md`).\n- Bug fixes and reliability improvements in CLI subcommands and onboarding flows.\n- Updated documentation (SKILL.md) to clarify onboarding, drift detection, and parameters.\n\nv2.7.0 | 2026-08-22T05:18:53.949Z | auto\n\n**2.7.0 brings enhanced onboarding and drift detection improvements.**\n\n- Improved onboarding drift detection logic with updated project root resolution and user prompts.\n- Added new test for refresh and reconcile functionality (`tests/test_refresh_reconcile.py`).\n- Updated documentation (SKILL.md, CHANGELOG.md, RELEASE.md) for greater clarity and completeness.\n- Various internal module and test adjustments to align with the revised onboarding/refresh process.\n- Removed deprecated `skill-card.md` file.\n\nv2.6.0 | 2026-08-21T14:38:23.183Z | auto\n\n## iterate-skill 2.6.0\n\n- Updated and expanded documentation in SKILL.md, including more detailed onboarding, review modes, and workflow explanations.\n- Adjusted file and project onboarding discovery logic for improved multi-project (monorepo) support.\n- Refined onboarding drift detection process and related configuration instructions.\n- Removed legacy file `skill-card.md`.\n- Updated or added test scripts and tooling (tests, config validation, badge updater, CLI).\n- Minor schema and configuration updates.\n\nv2.5.0 | 2026-08-21T05:49:20.532Z | auto\n\n**2.5.0 Summary:**\nIntroduces the new `show` CLI subcommand and various enhancements across onboarding, CLI behaviors, and documentation.\n\n- Added `iterate_cli/show.py` implementing a new `show` CLI command for displaying iteration state or artifacts.\n- Enhanced onboarding logic and drift detection to improve project root detection and user prompts.\n- Improved CLI argument handling and documentation, especially in onboarding and wizard flows.\n- Updated and clarified documentation in SKILL.md, README.md, and supporting markdowns.\n- Removed obsolete `skill-card.md` file.\n- Updated tests and validation scripts to match onboarding and CLI refinements.\n\nv2.4.5 | 2026-08-21T02:04:51.475Z | auto\n\nVersion 2.4.5\n\n- Updated documentation: Improved clarity and detail in SKILL.md, README.md, and related tool manifests.\n- Enhanced npm-installer: Added LICENSE file and localized documentation updates for npm installer package.\n- Bug fixes and test improvements across CLI, installer scripts, and validation tools.\n- Minor improvements to internal code structure and configuration schema.\n- Removed obsolete skill-card.md file.\n\nv2.4.1 | 2026-08-19T14:46:30.322Z | auto\n\n## iterate-skill v2.4.1\n\n- Updated documentation in SKILL.md for clarity and improved guidance.\n- Removed obsolete skill-card.md; all documentation now consolidated.\n- Configuration and package metadata updated in config files (schema and YAML), pyproject.toml, and package.json.\n- Internal files in iterate_cli and npm-installer updated for consistency with latest versioning and configuration.\n- Minor text and metadata updates to reflect v2.4.1 release.\n\nv2.4.0 | 2026-08-19T12:58:44.046Z | auto\n\n**New in 2.4.0: Adds end-to-end download statistics badge, tighter review meta-checks**\n\n- Added download statistics badge and update script to display up-to-date npm/PyPI downloads.\n- Introduced a hard evidence validation gate: meta-review now enforces that every finding's file/line anchors to real, actually-read code, disallowing fabricated paths/numbers.\n- Improved documentation: README, SKILL.md, and config files updated for clarity and recent features.\n- Removed legacy skill-card.md (now superseded by badges and README improvements).\n- Enhanced test coverage related to download badge update logic.\n\nv2.3.20 | 2026-08-19T11:45:36.097Z | auto\n\n- Improved onboarding and drift detection logic, with clearer user prompts and process explanations.\n- Updated documentation in SKILL.md for onboarding, review-only mode, and core workflow details.\n- Removed redundant file: skill-card.md.\n- Various internal updates and minor improvements across CLI and onboarding modules.\n\nv2.3.19 | 2026-08-18T01:58:56.795Z | auto\n\n- Added Chinese (Simplified) README to npm-installer for improved international support.\n- Updated documentation files for clarity and coverage (README, DESIGN, examples).\n- Revised onboarding and validation flows; improved review and reporting logic.\n- Minor refactors across CLI modules and example projects.\n- Removed outdated skill-card.md; consolidated documentation.\n- Dependency and config updates for maintenance and consistency.\n\nv2.3.18 | 2026-08-17T12:07:31.047Z | auto\n\n**Added Node.js installer module and improved test coverage.**\n\n- Introduced a new `npm-installer` directory with Node.js CLI, installer logic, and tests for cross-ecosystem skill installation.\n- Updated multiple core files for better CLI personalization and onboarding workflows.\n- Expanded and revised test cases, including installation and validation scenarios.\n- Removed the obsolete `skill-card.md` file.\n- Updated documentation (CHANGELOG, RELEASE, SKILL.md) for new features and improvements.\n\nv2.3.17 | 2026-08-17T07:08:33.636Z | auto\n\n**iterate-skill v2.3.17 Changelog**\n\n- Removed all code and assets related to the deprecated iterate-plugin harness (entire `harness/iterate-plugin` directory and associated files).\n- Updated documentation files (CHANGELOG.md, DESIGN-iterate-harness.md, SKILL.md) to reflect removal of the harness and any outdated references.\n- Made necessary updates in `iterate_cli/__init__.py` and `pyproject.toml` to remove plugin harness integration.\n- Significantly reduced repository footprint by deleting 45 harness-specific files.\n\nv2.3.16 | 2026-08-17T06:45:31.391Z | auto\n\n**Summary:** Major update with new plugin system, npm installer, and enhanced onboarding/testing.\n\n- Introduced iterate-plugin and modular CLI/plugin architecture.\n- Added npm-installer component for independent dependency management.\n- Expanded onboarding and drift detection logic in onboarding flow and documentation.\n- Improved test coverage: new tests for CLI, install, and plugin tools.\n- Removed deprecated files (e.g., skill-card.md); updated documentation and configuration.\n\nv2.3.15 | 2026-08-17T01:59:27.346Z | auto\n\n- Major internal cleanup: removed 32 files, including legacy test files, build artifacts, and Python .pyc caches.\n- Updated dependencies and source files for the iterate-plugin harness.\n- Documentation and design guides (CHANGELOG.md, DESIGN-iterate-harness.md, SKILL.md) updated for clarity and accuracy.\n- No user-facing changes to skill invocation or core logic.\n\nv2.3.14 | 2026-08-16T05:54:10.216Z | auto\n\n2.3.14 introduces significant updates including new features, tests, and internal improvements.\n\n- Added 32 new files, including new tools, tests, and compiled files for iterate-plugin and iterate_cli.\n- Enhanced decision logging and introduced new review parsing and triage modules.\n- Updated existing scripts and configuration files to support new workflows and improve reliability.\n- Removed obsolete documentation (skill-card.md).\n- General codebase refactoring and expanded test coverage.\n\nv2.3.13 | 2026-08-16T03:14:30.409Z | auto\n\nVersion 2.3.13\n\n- Updated SKILL.md to reflect the new version and refine documentation; removed deprecated or outdated content.\n- Enhanced and clarified onboarding and drift detection instructions within SKILL.md.\n- Removed obsolete file: skill-card.md.\n- Minor maintenance and adjustments in source and test files (e.g., iterate_cli/__init__.py, pyproject.toml, tests/test_doctor.py).\n- General cleanup and reorganization for improved consistency and readability.\n\nv2.3.12 | 2026-08-16T02:45:27.129Z | user\n\ndoctor --fix auto-repair; schema-aligned checks; jsonschema runtime dep\n\nv2.3.9 | 2026-08-15T10:34:41.353Z | user\n\nFix human-reader banner placement so it renders on ClawHub, add English banner, and visually separate banner from overview.\n\nv2.3.8 | 2026-08-15T09:52:03.917Z | auto\n\nIterate Skill 2.3.8 Changelog\n\n- Documentation updated: SKILL.md received content changes and revision.\n- Obsolete or duplicate file removed: skill-card.md deleted.\n- No functional or behavior changes to core skill logic; update is documentation-focused.\n\nv2.3.7 | 2026-08-14T13:56:04.384Z | auto\n\n- Added a test suite for TUI functionality (`tests/test_tui.py`).\n- Improved documentation across plugin, CLI, and SDK files.\n- Updated and clarified onboarding and core workflow descriptions in SKILL.md.\n- Refined plugin packaging details (added LICENSE, updated `package.json`).\n- Removed `skill-card.md` (legacy/duplicate documentation).\n\nv2.3.6 | 2026-08-14T10:28:04.279Z | auto\n\n- Add tests for config and context loaders, improving test coverage.\n- Update multiple core files for both CLI and plugin logic.\n- Remove the deprecated skill-card.md documentation file.\n- Minor updates to documentation and configuration structure in SKILL.md and config files.\n\nv2.3.5 | 2026-08-14T08:36:04.922Z | auto\n\n**Added review-only mode, enabling pure codebase health checks with meta-review capabilities.**\n\n- Introduced `review-only` / `dry-run` mode: repeated multi-round parallel review without modifying files, generating a formal report and meta-review for consistency.\n- CLI and skill parameters now accept `review-only` or `dry-run` for pure audit flows.\n- Added harness/iterate-plugin with separation of review logic, meta-review, and test cases.\n- Documentation and skill manifest updated for review-only feature and parameter handling.\n- Various updates and architecture improvements across CLI, TUI, validation scripts, and onboarding plugin structure.\n\nv2.3.3 | 2026-08-14T07:04:21.628Z | auto\n\n## iterate-skill 2.3.3\n\n- CLI onboarding logic refactored and flow clarified; improved handling for first-time and repeat onboarding.\n- Full and incremental onboarding/refresh commands and flow are now explained in updated docs.\n- Added DESIGN-iterate-harness.md for new iteration harness architecture/design docs.\n- Updated SKILL.md and README.md for more accurate onboarding, drift detection, and CLI guidance.\n- Obsolete skill-card.md file removed for clarity and to reduce confusion.\n\nv2.3.2 | 2026-08-14T01:19:22.378Z | auto\n\n**Summary:**\nAdded drift_ignore support for onboarding drift detection and improved configuration and onboarding flows.\n\n- Added support for onboarding.drift_ignore to skip specified manifests from drift checks.\n- Updated onboarding drift detection logic to honor onboarding.drift_ignore configuration.\n- Improved onboarding instructions and configuration schema.\n- Removed deprecated npm-installer code and related files.\n- Added new test coverage for drift_ignore behavior.\n- Updated documentation for onboarding, drift detection, and parameters.\n\nv2.3.1 | 2026-08-13T13:28:25.026Z | auto\n\niterate-skill 2.3.1\n\n- Improves onboarding project root detection, clarifies behavior for monorepos and multi-project workspaces.\n- Enhances AI onboarding flow to always clearly inform users on first use/initialization.\n- SKILL.md and docs updated for clearer onboarding instructions and multi-root scenarios; onboarding messaging now explicit.\n- Removes legacy CI config and outdated files; adds uv.lock for dependency management.\n- CLI onboarding guidance and commands are now highlighted in docs.\n\nv2.3.0 | 2026-08-04T04:28:03.259Z | auto\n\niterate-skill 2.3.0\n\n- Bumped skill version to 2.3.0.\n- Updated configuration and documentation files: CHANGELOG.md, README.md, SKILL.md.\n- Updated package version in `npm-installer/package.json` and `pyproject.toml`.\n- Internal codebase update in `iterate_cli/__init__.py`.\n- No breaking changes; see documentation for details.\n\nv2.2.9 | 2026-08-04T04:17:06.861Z | auto\n\n- Bumped version to 2.2.9.\n- Updated documentation and instructions in SKILL.md, README.md, and CHANGELOG.md.\n- Improvements to installer packaging (npm-installer and pyproject.toml updated).\n- Deleted legacy file: skill-card.md.\n- Minor workflow and codebase maintenance.\n\nv2.2.8 | 2026-08-04T00:38:34.534Z | user\n\n- The skill card file (skill-card.md) has been removed.\n- Documentation clarified that merge and push actions are now opt-in and disabled by default (previously default on).\n- No code or logic changes; this update affects documentation and packaging only.\n\nv2.2.7 | 2026-08-03T14:51:20.143Z | auto\n\n## iterate-skill 2.2.7\n\n- Updated documentation in SKILL.md; version bump to 2.2.7.\n- Synchronized version numbers across project files.\n- Minor internal changes across 6 files (docs, CLI, installer, and package metadata).\n- No user-facing behavioral changes.\n\nv2.2.6 | 2026-08-03T14:31:13.706Z | user\n\n**v2.2.6 adds a cross-platform installer and improves onboarding compatibility.**\n\n- Introduced an npm-based installer (`npm-installer/`) for easy cross-platform CLI installation via `npx iterate-skill-installer`.\n- Added onboarding templates and TUI (text user interface) support files.\n- CLI install instructions updated: users can now choose between `npx` and `pip`.\n- Improved onboarding: `iterate.config.yaml`'s onboarding block must include `channel: \"ai\"`, `completed_at` (ISO 8601), and `fingerprints` for status tracking.\n- Removed legacy `skill-card.md`.\n\nArchive index:\n\nArchive v3.4.4: 112 files, 710596 bytes\n\nFiles: badges/downloads.json (118b), CHANGELOG.md (138460b), config/config.schema.json (16757b), config/dimensions.yaml (2831b), config/dimensions/architecture.yaml (289b), config/dimensions/correctness.yaml (407b), config/dimensions/frontend-backend.yaml (307b), config/dimensions/performance.yaml (306b), config/dimensions/security.yaml (300b), config/dimensions/spec-compliance.yaml (266b), config/dimensions/style-tests.yaml (314b), config/dimensions/tech-debt.yaml (281b), config/dimensions/ui-ux.yaml (261b), config/iterate.config.yaml (9146b), CONTRIBUTING.md (2396b), DESIGN-iterate-harness.md (231388b), DESIGN-iterate-plugin.md (19925b), DESIGN-iterate-skill.md (17627b), examples/python-project.md (1602b), examples/swift-project.md (1322b), examples/typescript-project.md (1437b), iterate_cli/__init__.py (108b), iterate_cli/__main__.py (155b), iterate_cli/cli.py (68678b), iterate_cli/configcmd.py (17532b), iterate_cli/data/config.schema.json (16757b), iterate_cli/data/ITERATE.template.md (1864b), iterate_cli/dimension_sets.py (7015b), iterate_cli/doctor.py (55364b), iterate_cli/fingerprint.py (12236b), iterate_cli/generator.py (31570b), iterate_cli/guard.py (32177b), iterate_cli/personalize.py (68360b), iterate_cli/refresh.py (34234b), iterate_cli/scan.py (11086b), iterate_cli/show.py (15735b), iterate_cli/tui.py (14348b), iterate_cli/updater.py (42769b), iterate_cli/wizard.py (45319b), kernel/fixtures/decision-log-entry.ok-01.json (346b), kernel/fixtures/evidence-pack.ok-01.json (1727b), kernel/fixtures/evidence-pack.ok-02.json (794b), kernel/fixtures/evidence-pack.ok-03.json (1836b), kernel/fixtures/evidence-pack.ok-04-legacy-draft.json (1451b), kernel/fixtures/evidence-pack.ok-05-pixelbounds-null.json (1352b), kernel/fixtures/recipe-config.ok-01.json (628b), kernel/fixtures/report.ok-01.html (1771b), kernel/fixtures/report.ok-01.md (1054b), kernel/package-lock.json (4124b), kernel/package.json (728b), kernel/schemas/decision-log-entry.schema.json (1228b), kernel/schemas/evidence-pack.schema.json (9111b), kernel/schemas/recipe-config.schema.json (1078b), kernel/src/decision-log-entry.ts (1009b), kernel/src/errors.ts (768b), kernel/src/evidence-pack.ts (12063b), kernel/src/index.ts (2460b), kernel/src/parse.ts (2150b), kernel/src/recipe-config.ts (843b), kernel/src/schemas.ts (1352b), kernel/test/decision-log-entry.test.mjs (3345b), kernel/test/evidence-pack.test.mjs (11076b), kernel/test/helpers.mjs (1000b), kernel/test/recipe-config.test.mjs (2863b), kernel/test/roundtrip.test.mjs (2529b), kernel/tsconfig.json (508b), LICENSE (1083b), npm-installer/bin/cli.js (2134b), npm-installer/lib/installer.js (50270b), npm-installer/LICENSE (1067b), npm-installer/package.json (946b), npm-installer/README.md (3054b), npm-installer/README.zh-CN.md (2900b), npm-installer/test/mode.test.js (20495b), pyproject.toml (1855b), README.md (49468b), README.zh-CN.md (47880b), RELEASE.md (92432b), scripts/check.sh (2333b), scripts/install.py (107352b)\n\nFile v3.4.4:SKILL.md\n\n---\nname: iterate\nslug: iterate-skill\ndisplayName: Iterate\ndescription: Fully automated multi-round code iteration with configurable N-dimension parallel review, onboarding/personalization, and a cross-assistant installer/update system with mandatory SHA256 checksum verification. v3.0 adds a dual-mode (the original iterate mode plus a defensive-programming mode via /iterate defensive) that performs normal incremental coding tasks with defensive discipline end-to-end.\nversion: 3.4.4\npermissions:\n file_read: true\n file_write: true\n shell: true\n git: true\n network: \"github.com only (release tarball + checksum verification)\"\n sensitive_files:\n skip: [\".env\", \".env.*\", \"*.key\", \"secrets/\", \"*.pem\", \"*.p12\", \"*.crt\", \"*.cer\", \"credentials.json\", \".aws/\", \".ssh/\"]\n---\n\n# /iterate `` `[rounds]` `[no-limit]`\n\n# /iterate defensive ``（防御式编程模式 / Defensive-Programming Mode）\n\n> **面向人类读者**：本文件是供 AI 助手消费的 Skill 指令。若您是开发者或浏览者，欢迎前往 GitHub 仓库 [jingzhao-l/iterate-skill](https://github.com/jingzhao-l/iterate-skill) 阅读 README，详细了解本 Skill 及其附属生态（iterate-harness、iterate-plugin、CLI 等）。\n>\n> **For human readers (English)**: This file is a Skill manifest consumed by AI assistants. If you are a developer or a human visitor, welcome to the GitHub repository [jingzhao-l/iterate-skill](https://github.com/jingzhao-l/iterate-skill) — read the README to learn more about this Skill and its ecosystem (iterate-harness, iterate-plugin, CLI, etc.).\n\n---\n\n## 简介 / Overview\n\n> 中文：全自动多轮代码迭代。每轮从 N 个已启用维度并行审查整个项目（默认 9 个），原子问题直接修复，架构问题经用户批准后由子代理串行执行，验证通过后（合并与推送为 opt-in，默认关闭）循环直到零 findings 或达到轮数上限。\n>\n> English: Fully automated multi-round code iteration. Each round launches N parallel dimension reviewers across the project (default 9), fixes atomic issues directly, executes architectural issues after user approval via serial sub-agents, validates, and loops until zero findings or max rounds (merge/push are opt-in and disabled by default).\n\n**v3.0 双模式 / v3.0 dual-mode**：本 Skill 现为**双模式**——\n\n- **iterate 模式**（原 `/iterate`，默认，v2 全部能力完整保留）：审查 → 修复 → 验证 → 收敛闭环。\n- **防御式编程模式**（新增 `/iterate defensive`）：面向**用户让 AI 做正常增量式编程任务**的场景（新增功能、修 bug、重构等），宿主 AI 从动手前到收尾**从头至尾贯彻防御式编程理念**（四步协议：pre-check → 最小步进编码 → 每步 post-check → invariant + iterate 收敛门禁），以 iterate 闭环收尾作为**交付门禁**（不收敛不交付）。\n\n> Defensive-Programming Mode (v3.0, via `/iterate defensive`): for the scenario where the **user asks the AI to do a normal incremental coding task** (add a feature, fix a bug, refactor). The host AI performs that task end-to-end with defensive discipline — a four-step protocol: `pre-check` before touching anything → minimal-step editing (validate at the trust boundary) → `post-check` after every edit → `invariant` + the iterate convergence loop as a **delivery gate** (no convergence, no delivery).\n\n---\n\n## 何时使用 / When to Apply\n\n**iterate 模式**适用于以下场景：\n\n- 需要系统性提升代码质量、修复潜在 bug 或安全漏洞。\n- 项目进入重构、迭代收尾或发布前的审查阶段。\n- 需要多维度（正确性、安全、性能、架构等）并行审查。\n- 希望将原子问题自动修复，将架构问题经审批后修复。\n\n**防御式编程模式**（`/iterate defensive`）适用于**用户让 AI 做正常增量式编程任务**的场景：\n\n- 用户给一个**具体的增量式编程任务**：新增功能、修复 bug、重构模块、接入 API、补测试等。\n- 该任务需要**动手改代码**（不是纯审查），且用户希望 AI **从头至尾按防御式编程纪律**完成——动手前校验、最小步进、每步后校验、收尾门禁。\n- 典型场景：`/iterate defensive implement user-settings page`、`/iterate defensive fix the null-pointer bug in parser.py`、`/iterate defensive refactor auth to use a middleware`。\n- **判断要点**：任务是\"让 AI 干活产出代码\"而非\"让 AI 审查已有代码\"，就应进入防御式编程模式；任务若需多轮并行审查收敛，仍可用 iterate 模式，二者以**本次调用的 goal 形态**区分。\n\n**纯审查模式 / review-only mode**：当调用参数含 `review-only` 或 `dry-run` 时，本 Skill 只做**只读健康检查**，绝不修改任何文件：\n- 反复多轮并行审查，直到某一轮出现 0 个新 findings（收敛）。\n- 生成审查报告（含每轮收敛统计、按严重级别/维度汇总、修复优先级建议）。\n- **再审查这份报告本身**（meta-review：校验报告内部一致性——总数匹配、严重级别汇总、维度汇总、排序、收敛数学），给出带 `approved` / `needs_revision` 判定的**最终审查报告**。meta-review 同时跑硬证据门禁：逐条校验 finding 的 `file`/`line` 是否真实存在，子代理只允许锚定实际读过的真实代码，伪造路径/行号即以 `EVIDENCE_VIOLATION` 判 `needs_revision`。\n- 适用于发布前体检、代码质量审计、不想让 AI 动代码的场景。\n\nThis Skill is appropriate when:\n\n- You need a systematic code quality improvement, bug fix, or security hardening pass.\n- The project is in refactoring, pre-release, or iteration wrap-up phase.\n- You want parallel multi-dimension review (correctness, security, performance, architecture, etc.).\n- You want atomic issues fixed automatically and architectural issues fixed after approval.\n\n**Defensive-Programming Mode** (`/iterate defensive`) applies when the **user asks the AI to do a normal incremental coding task**:\nyou are asked to implement a feature, fix a bug, refactor a module, integrate an API, or add tests —\nand you must do that task end-to-end with defensive discipline (pre-check → minimal-step editing →\npost-check after every edit → invariant + iterate convergence as a delivery gate).\n\n**review-only / dry-run mode** applies when the invocation includes `review-only` or `dry-run`:\nit performs a read-only health check that never modifies files — repeated parallel review rounds until a\nround finds 0 new findings (convergence), produces a review report, then meta-reviews that report\n(validating internal consistency) and emits a final report with an `approved` / `needs_revision` verdict.\nThe meta-review also runs the hard code-evidence gate: every finding's `file`/`line` is validated against\nreal files on disk, so reviewers may only anchor to code they actually read — fabricated paths or invented\nline numbers surface as `EVIDENCE_VIOLATION` and force `needs_revision`.\nUse it for pre-release health checks, audits, or any case where you do not want the AI to touch code.\n\n## 何时跳过 / When to Skip\n\n**iterate 模式**不适用于以下场景：\n\n- 仅需要单次、简单的代码编辑（不需要多轮审查）——**此类场景应改用防御式编程模式 `/iterate defensive`**（正是为\"让 AI 做正常增量式编程任务\"而设）。\n- 没有可用的验证命令（`validation.commands` 未配置）——防御式模式下 `guard post-check` / `invariant` 会依赖验证命令，缺失时校验退化。**自 v3.0.1 起**：若项目*已 onboarded*（存在非空 `iterate.config.yaml`）但 `validation.commands` 为空，`guard pre-check` 将 **fail-closed**（退出码 1、`PASS`/`FAIL` 为 `FAIL`）——因为它承诺的 post-check 必然失败，不应给出\"可以开工\"的绿灯；宿主 AI 收到 `FAIL` 应先补配置 `validation.commands`。全新项目（尚无配置）则正常降级放行。\n- 只需要 UI/UX 设计建议（请使用 UI/UX Pro Max 等专业设计 Skill）。\n\nDo **not** use this Skill in **iterate mode** when:\n\n- A single, simple edit is sufficient (no multi-round review needed) — **use `/iterate defensive` instead** (that is exactly the incremental-coding-task scenario it serves).\n- No validation commands are configured in `validation.commands`. **Since v3.0.1**: for an *onboarded* project (a non-empty `iterate.config.yaml` exists) with empty `validation.commands`, `guard pre-check` **fails closed** (exit code 1) instead of handing out a misleading \"clear to start\" green light — configure `validation.commands` first. A brand-new project with no config yet still degrades gracefully (pass).\n- You only need UI/UX design advice (use a dedicated design Skill like UI/UX Pro Max).\n\n---\n\n## 参数 / Parameters\n\n调用格式 / Invocation:\n\n- **iterate 模式**：`/iterate [rounds] [no-limit]`\n- **防御式编程模式**：`/iterate defensive `（v3.0 新增；可用 `iterate.config.yaml` 的 `mode: defensive` 设为本次调用默认，仍可用显式 `defensive` 覆盖）\n\n参数通过 [Agent Skills](https://agentskills.io/) 标准占位符注入：\n\n| 占位符 / Placeholder | 含义 / Meaning | 默认值 / Default |\n|---------------------|----------------|------------------|\n| `$goal` / `$0` | 迭代目标 / Iteration goal | required |\n| `$rounds` / `$1` | 最大轮数 / Max rounds | `7` |\n| `$limit_mode` / `$2` | 若设为 `no-limit`，则最大轮数为 50（硬上限）/ Set to `no-limit` for hard cap 50 | — |\n| `$mode` / `$3` | `review-only` / `dry-run` → **纯审查模式**（反复审查直到零 findings，绝不修改文件）；`defensive` → **防御式编程模式**（按四步协议从头至尾完成增量式编程任务，iterate 闭环收尾作为交付门禁）/ `review-only`/`dry-run` → pure-review mode (never touches files); `defensive` → defensive-programming mode (four-step protocol on an incremental coding task, iterate loop as delivery gate) | 默认迭代模式 |\n| `$ARGUMENTS` | 用户输入的全部参数原样字符串 / Raw argument string | — |\n\n示例 / Examples：\n- `/iterate improve error handling`\n- `/iterate improve error handling 10`\n- `/iterate improve error handling no-limit`\n- `/iterate review the codebase review-only`（纯审查模式：只审查不改代码，反复审查到零 findings，出审查报告，再审查报告给出最终审查报告）\n- `/iterate full health check --review-only`（同上，纯审查别名）\n- `/iterate defensive implement user-settings page`（防御式编程模式：让 AI 正常写代码实现功能，从头至尾防御式纪律 + 收尾门禁）\n- `/iterate defensive fix the null-pointer bug in parser.py`\n- `/iterate defensive: refactor auth to middleware`\n\n---\n\n## 防御式编程模式 / Defensive-Programming Mode\n\n> **本节仅描述防御式编程模式（`/iterate defensive`）的行为。iterate 模式（`/iterate`）行为与 v2 完全一致，零回归。**\n>\n> **适用场景**：用户让 AI 做**正常增量式编程任务**（新增功能、修 bug、重构、接入 API、补测试）——动手改代码、产出真实可运行结果，而非纯审查。宿主 AI 从动手前到收尾**从头至尾贯彻防御式编程理念**，以 iterate 闭环收尾作为交付门禁。\n\n### 防御式编程心智模型 / The Defensive Mindset\n\n防御式编程是**编码时的心智模型**（软件工程经典定义），不是\"审查-修复-收敛\"流程；iterate 本身就是防御式编程的一种实现（审查环节的防御），本模式把整套心智模型**前移到编码过程本身**：\n\n1. **最小化假设 / Minimize assumptions**：假设事情会出错，主动预测并容忍问题，而非乐观假设\"应该没事\"。\n2. **信任边界验证 / Validate at trust boundaries**：数据从\"不可信来源\"进入代码的那一刻必须验证；内部状态可信任，**外部输入必须验证**。\n3. **快速失败、响亮失败 / Fail fast, fail loud**：错误一发生立即停止、报错、回滚，绝不带病继续。\n4. **前置/后置条件 + 断言 / Pre/post-conditions + assertions**：每个函数声明要求什么（前置）、保证什么（后置），用断言守卫假设。\n\n### 四步防御式协议 / Four-Step Defensive Protocol\n\n| 阶段 / Phase | 防御式原则 / Principle | 落地动作 / Action |\n|---|---|---|\n| **① 动手前 / Before** | 最小化假设 + 前置条件 | 声明\"我假设什么成立\"（目标范围、文件存在、git 干净、依赖就绪）；跑 `iterate guard pre-check ` 做**确定性前置校验**；FAIL 则先处理（恢复干净起点）再动手，绝不带病开工 |\n| **② 动手时 / During** | 信任边界验证 + 最小步进 | 每次只做**最小步进修改**；写入前验证目标路径在允许范围、命令在 `validation.commands` 精确白名单内；对外部输入在进入代码的边界处加校验；保持修改原子性（可回滚） |\n| **③ 动手后 / After** | fail-fast + 后置条件 | **每次改动后**跑 `iterate guard post-check [module...]`（精确执行配置的验证命令）；FAIL 则立即修复或回滚，记录假设是否被证伪；不通过不进入下一步 |\n| **④ 收尾 / Delivery** | 不变量守护 + 收敛门禁 | `iterate invariant` 检查项目级不变量（`invariants.ensure` 文件断言 + `invariants.commands`）；随后跑 **9 维度审查 → 修复 → 验证 → 收敛**（即 v2 完整 iterate 闭环）作为**交付门禁**——**不收敛不交付** |\n\n### 防御式 CLI 确定性校验 / Deterministic CLI Enforcement\n\n防御式理念必须靠 CLI 确定性校验落地（prompt 指令不可靠）。宿主 AI 在防御式模式下按下表调用：\n\n| 命令 / Command | 时机 / When | 输出 / Output | 契约 / Contract |\n|---|---|---|---|\n| `iterate guard pre-check [paths...]` | 动手前 | `PASS/FAIL` + 逐项结果 | 目标存在、git 干净、依赖 manifest 就绪、验证命令配置安全、每个验证命令对应的可执行工具在 PATH 上（shell 内建除外）；退出码 0 = 可以开工，1 = 禁止开工 |\n| `iterate guard post-check [module...]` | 每次改动后 | `PASS/FAIL` + 逐项结果 | 精确执行 `validation.commands.`（运行时唯一权威白名单）；退出码 0 = 本次改动安全，1 = 必须先修复或回滚 |\n| `iterate invariant` | 收尾交付前 | `PASS/FAIL` + 违反项明细 | 校验 `invariants.ensure` 文件断言 + `invariants.commands`；`ensure` 只接受项目根目录内的相对路径（拒绝绝对路径与越出项目根的 `../` 逃逸）；无 `invariants` 段时退化为 `validation.commands`；退出码 0 = 不变量成立，1 = 存在违反项 |\n\n### 交付门禁 / Delivery Gate\n\n- **不收敛不交付**：防御式模式的收尾必须跑完整 iterate 闭环（9 维度审查 → 修复 → 验证 → 收敛），任一维度仍有未解决 findings 或 `iterate invariant` 不通过，**不得交付**，必须继续修复直到收敛。\n- **假设记录**：动手前声明的假设，在收尾时逐条回放——被证伪的假设必须说明如何被验证/修复。\n- **输出交付总结**：改动清单、验证证据（各步 `guard` / `invariant` 结果）、残留风险与豁免。若某项不变量被有意豁免，在交付总结中**列明违反项与豁免理由**（仅作为报告小节记录，不写入配置——配置里不存在豁免键，schema 拒绝未知字段）。\n\n---\n\n## 问题分类标准 / Issue Classification\n\n### 原子问题（Atomic） / Atomic Issues\n\n满足以下**全部**条件：\n\n- 改动在**单个文件**内。\n- 改动在**单个函数/方法**内（或最多 3 个相邻的同类方法）。\n- 预计改动 ≤ **20 行**（可通过配置调整）。\n\n原子问题**不进入用户审批流程**，由主模型直接修复。\n\nAn issue is atomic when **all** of the following are true:\n\n- Changes are within a **single file**.\n- Changes are within a **single function/method** (or ≤3 adjacent similar methods).\n- Expected changes are ≤ **20 lines** (configurable).\n\nAtomic issues are **fixed directly by the main model** without user approval.\n\n### 架构问题（Architectural） / Architectural Issues\n\n满足以下**任一**条件：\n\n- 跨多个文件。\n- 涉及 API / 协议 / 数据模型变更。\n- 需要新增类 / 模块 / 文件。\n- 预计改动 > **20 行**。\n\n架构问题**必须经用户批准后**才能执行，由子代理串行完成。\n\nAn issue is architectural when **any** of the following is true:\n\n- Cross-file changes.\n- API / protocol / data model changes.\n- New classes / modules / files needed.\n- Expected changes are > **20 lines**.\n\nArchitectural issues **require user approval** and are executed by sub-agents serially.\n\n**关键原则 / Key Principle**：原子问题和架构问题同样重要，都必须修复。区别仅在于是否需要用户批准以及由谁执行。\n\n---\n\n## 核心流程 / Core Workflow\n\n> **本节描述 iterate 模式（`/iterate`）的完整闭环，与 v2 完全一致。** 防御式编程模式（`/iterate defensive`）的执行请见上文「防御式编程模式」一节：其收尾阶段（第 ④ 步）即复用本节完整 iterate 闭环作为交付门禁，其余各步（① 动手前 / ② 动手时 / ③ 动手后）在编码过程中注入防御式纪律。\n\n```text\nStep 0 — Onboarding Check\n └─ Locate project root → check ITERATE.md → drift detection → (onboard if needed)\n\nSetup\n └─ Extract goal → load config → read project context (ITERATE.md → CLAUDE.md → …) → create isolated branch/worktree\n\nLoop (round = 1 .. max_rounds)\n ├─ Phase 0: Dimension Planning (route goal → dimension_sets | ad-hoc redefine, bounded record)\n ├─ Phase 1: N-dimension parallel review (N = enabled dimensions count, default 9)\n ├─ Phase 2: Atomic fixes (direct)\n ├─ Phase 3: Architectural fixes (approval → serial sub-agents)\n ├─ Phase 4: Record round results\n └─ Phase 5: Validate → merge → push\n\nSummary\n```\n\n---\n\n## Step 0 — Onboarding 检查 / Onboarding Check\n\n每次调用 `/iterate` 时，**首先**执行 onboarding 检查。Onboarding 是为当前项目生成定制化知识库（`ITERATE.md`）和项目级配置（`iterate.config.yaml` 中的 `onboarding` 段）的过程。\n\n### 为什么需要 Onboarding\n\n- **validation.commands 精准化**：默认配置中的验证命令只是示例，onboarding 根据项目实际技术栈生成正确的命令。\n- **维度定制化**：无前端的项目不需要 `ui-ux` 维度，无 specs/ 的项目不需要 `spec-compliance`——onboarding 避免空转浪费算力。\n- **项目知识沉淀**：`ITERATE.md` 记录项目概述、技术栈、模块地图、审查注意点，供后续每轮审查参考。\n\n### 检查流程\n\n1. **定位项目根目录 / Locate project root**\n - 以当前工作目录为起点向上查找；命中优先级：**包含 `ITERATE.md` 或 `iterate.config.yaml` 的目录 > 包含 `.git` 的目录**。\n - **Monorepo / 多子项目提示**：若同时存在多个候选根（如外层 git 根 + 内层某子项目也含 manifest），以**最近的含 `ITERATE.md` / `iterate.config.yaml` 的目录**为准；若无明确唯一候选，用 `AskUserQuestion` 让用户确认审查范围，避免误审到无关子项目。\n - 若向上查找到文件系统根仍未找到，则使用当前工作目录作为项目根目录，并提示用户确认。\n\n2. **检查 onboarding 状态 / Check onboarding status**\n - 检查项目根目录下是否存在 `ITERATE.md`。\n - **存在** → 进入漂移检测（下一步）。\n - **不存在** → **先向用户明确说明**\"这是首次使用，将先进行项目初始化（Onboarding）\"，再暂停迭代进入 **AI Onboarding 流程**（见下文）。不要让用户误以为 skill 失效或卡住；完成后继续 Step 1。\n\n3. **漂移检测 / Drift detection**（仅在 `onboarding.drift_check` 为 `true` 时执行）\n - 读取 `iterate.config.yaml` 中的 `onboarding.fingerprints`（manifest 文件的 SHA-256 哈希）。\n - 重新计算当前 manifest 文件的哈希并比对；`onboarding.drift_ignore` 中列出的 manifest（如锁文件）会被跳过，不计入漂移。\n - **无漂移** → 静默通过，进入 Step 1。\n - **有漂移**（manifest 新增/删除/内容变更）→ **非阻塞**警告，使用 `AskUserQuestion` 询问用户：\n - **继续（continue）**：本轮照旧使用现有 ITERATE.md。\n - **增量刷新（refresh）**：AI 重新扫描项目，更新 ITERATE.md 的 AI 维护区（用户手写区保留），更新指纹。\n - **完整重新 onboarding（reonboard）**：备份旧文件后走完整 onboarding 流程。\n\n> 漂移检测是**非阻塞**的——即使用户选择\"继续\"，迭代也会正常进行，只是使用可能过时的知识库。\n\n### AI Onboarding 流程 / AI Onboarding Flow\n\n当 `ITERATE.md` 不存在时，AI 执行以下流程（类似 Claude Code 首次生成 `CLAUDE.md`）：\n\n1. **告知并确认 / Inform and confirm**\n - 告知用户将扫描代码库生成 `ITERATE.md` 和配置，并说明这是首次使用所必需的初始化步骤。\n - 同时提示 CLI 备选：用户也可以运行 `iterate onboard` 在命令行中完成。\n - 参考 `templates/onboarding-playbook.md` 中的扫描清单和映射表（**仅供参考，需按项目实况调整**）。\n\n2. **扫描 / Scan**（并行只读）\n - 读取 manifest 文件（`package.json` / `pyproject.toml` / `Package.swift` / `go.mod` / `Cargo.toml` 等）。\n - 读取 2-3 层目录树，识别模块结构。\n - 检查 `specs/`、`tests/`、CI 配置的存在性。\n - 读取已有 `README.md` / `CLAUDE.md` 提取项目描述。\n - **绝不读取** `.env`、`.env.*`、`*.{key,pem,p12,crt,cer}`、`credentials.json`、`.aws/`、`.ssh/` 等敏感文件。\n\n3. **草拟 / Draft**\n - 基于扫描结果 + playbook 映射表草拟：\n - `ITERATE.md`：项目概述、技术栈、模块地图、推荐维度、iterate 注意点。\n - `iterate.config.yaml`：启用的 dimensions、`validation.commands`、`validation.command_whitelist`、指纹数据。\n - ITERATE.md 分为 **AI 维护区**（`` ~ `END`）和 **用户维护区**（`` ~ `END`）。刷新时只更新 AI 维护区。\n\n4. **用户确认 / User confirmation**\n - 展示摘要：识别的技术栈、拟启用维度及理由、**拟写入的 validation.commands 逐条列出**。\n - 用户可选：全部接受 / 修改 / 重扫。\n - **validation.commands 涉及后续自动执行，必须经用户显式确认。**\n\n5. **写入产物 / Write outputs**\n - 写入 `ITERATE.md` 和 `iterate.config.yaml`，其中 `onboarding` 段必须包含 `channel: \"ai\"`、`completed_at`（ISO 8601 时间戳）与 `fingerprints`，与 CLI 通道产出保持一致（否则 `iterate status` 会显示 `Channel: unknown`）。\n - 继续正常迭代流程（Step 1）。\n\n### CLI Onboarding（命令行通道）\n\n用户也可以在终端中运行 `iterate onboard` 完成相同流程：\n\n```bash\niterate onboard # 交互式向导（多路引导：首次/非首次自动分支）\niterate personalize # 个性化配置（项目中途追加约束，9 步向导）\niterate personalize --clear [--yes] # 清空所有个性化配置（结构化规则 + ITERATE.md 相关段落）\niterate show # 只读查看合并后的配置与个性化详情（支持 --json）\niterate refresh # 增量刷新（保留用户手写区；支持 --json / --dry-run --json 结构化报告）\niterate reonboard # 完整重新 onboarding（备份旧文件）\niterate doctor # 项目健康诊断（onboarding/config/维度/漂移等全项检查；--strict 将 warning 一并判失败；--fix 安全修复；--json / --json-out 结构化输出）\niterate status # 查看 onboarding 状态和漂移检测（--json 含 onboarded、config_exists/config_ok、drift_detected 与明细列表）\niterate guard pre-check [targets...] # 编辑前静态校验（目标存在/工作区干净/manifest 就绪；只读，从不执行命令；--json）\niterate guard post-check [targets...] # 编辑后执行 validation.commands 并核对结果（--dry-run 只预览命令不执行；--json）\niterate invariant # 项目级不变量校验（--dry-run 预览；--json）\niterate fingerprint verify # 校验 manifest 指纹漂移（--json）\niterate config # 非交互式查看全部可设配置值（支持 --json）\niterate config get # 读取单个配置项的解析值（支持 --json，输出 {\"key\": value}）\niterate config set # 校验并写回单个配置项（自动备份；--json 输出确认对象）\niterate update # 自更新：SHA-256 校验后刷新助手技能目录 + 重装 CLI（--check 只对比版本；--yes 跳过确认；--assistants 限定刷新范围，未知助手名报错而非静默跳过）\n```\n\nCLI 通道会自动扫描代码库并让你确认/调整技术栈与配置，适合希望手动控制 onboarding 过程的用户；AI 通道则完全由 AI 自动扫描生成。两者产出相同格式的 `ITERATE.md` 和 `iterate.config.yaml`。\n\n**多路引导 / Multi-Path Flow**：\n- **首次 onboarding**（无 ITERATE.md）：确认手动配置 → 基础 onboarding → 询问是否需要个性化配置。\n- **非首次 onboarding**（已有 ITERATE.md）：询问是否更新基础配置（不建议手动改）→ 询问是否进行个性化配置。\n\n`iterate config set ` 的 ``（扁平键，与 `iterate show` 输出的键一致）与点号路径别名（如 `git.use_worktree`、`reviewer.coverage_validation`）均可使用。\n\n**个性化配置 / Personalization**：捕获 AI 扫描不到的项目专属约束（禁区、风险区、已知意图、维度定制等 9 类）。运行 `iterate personalize` 可在项目中途随时追加，无需重做 onboarding。`iterate personalize --clear` 可一次清空所有个性化（结构化规则 + `ITERATE.md` 用户区中的相关段落，需确认或加 `--yes` 跳过）。`iterate show` 可只读查看合并后的配置与个性化详情（`--json` 输出结构化数据供脚本/CI 使用）。详见 README。\n\n安装 CLI：`npx iterate-skill-installer` 会自动安装 `iterate` CLI；也可手动 `pip install .` 或 `pipx install .`（从本仓库根目录）。\n\n---\n\n## Step 1 — 设定目标与隔离 / Setup\n\n1. **提取目标 / Extract goal**\n - 从 `$0` / `$goal` 读取迭代目标；若缺失则反问用户。\n - Read iteration goal from `$0` / `$goal`; ask if missing.\n\n2. **确定轮数 / Determine max rounds**\n - `maxRounds = $1` / `$rounds`，默认 `7`。\n - 若 `$2` / `$limit_mode` 为 `no-limit`，则 `maxRounds = 50`（硬上限）。\n - 解析失败时默认 `7` 并提示用户。\n\n3. **确定项目根目录 / Locate project root**\n - 以当前工作目录为起点向上查找；命中优先级：**含 `ITERATE.md` 或 `iterate.config.yaml` 的目录 > 含 `.git` 的目录**。\n - **Monorepo / 多子项目提示**：以**最近的含 `ITERATE.md` / `iterate.config.yaml` 的目录**为审查范围；无唯一候选时用 `AskUserQuestion` 让用户确认，避免误审无关子项目。\n - 若向上查找到文件系统根仍未找到，则使用当前工作目录作为项目根目录，并提示用户确认。\n - 该目录即为项目根目录，后续所有文件读取和命令执行均以此为准。\n\n4. **读取配置 / Load configuration**\n - **Master + Overrides 模式**：先加载技能安装目录下的 `config/iterate.config.yaml`（Master），再读取项目根目录的 `iterate.config.yaml`（Overrides）递归覆盖同名字段。\n - 合并规则为**深度合并（deep merge）**：对象字段递归合并键值；Overrides 中的列表字段会**完全替换** Master 中的同名列表（如 `dimensions`、`command_whitelist`）。\n - 若项目根目录不存在 Overrides，则完全使用 Master。\n - 将配置合并到运行参数；若合并后配置无法通过 schema 校验，立即报告错误并中止迭代。\n\n5. **读取个性化配置 / Load personalization**\n - 读取合并后配置中的 `personalization` 段（由 `iterate onboard` 或 `iterate personalize` 写入）。\n - 将以下字段加载到运行参数，后续 Phase 必须严格遵守：\n - `personalization.protected_paths`：glob 模式列表，**禁止修改匹配的文件**（Phase 2/3 修复时必须跳过）。\n - `personalization.risk_areas`：`[{path, reason}]`，修改这些路径前必须通过 `AskUserQuestion` 获得用户明确批准。\n - `personalization.known_intentional`：`[{file, line, dimension, reason}]`，Phase 1 汇总后必须过滤掉匹配的 findings（line=0 表示整个文件）。\n - `personalization.dimension_focus`：`[{dimension, focus}]`，Phase 1 启动 reviewer 时将对应 focus 追加到维度 prompt。\n - `personalization.fix_priority_order`：维度优先级列表（从高到低），Phase 2 排序时按此顺序优先修复。\n - `personalization.forbidden_fixes`：字符串列表，Phase 2/3 修复时**禁止使用**这些方式（如 `# noqa`、`try-catch 吞错`）。\n - 若 `personalization` 段不存在或为空，跳过本步，不影响正常流程。\n\n5b. **读取命名维度集 / Load dimension_sets**\n - 读取合并后配置中的 `dimension_sets`（由 onboarding 预置或用户手动命名，结构为 `{name: {dimensions: [...], focus?: {...}}}`）。\n - 将其整理为 `namedScopeSets` 供 Phase 0 范围路由使用；缺失 `` 时以全局 `dimensions` 为兜底。\n - `dimension_sets` 为空或不存在时不阻止流程，Phase 0 退化为纯 on-the-fly 逻辑。\n\n6. **读取项目上下文 / Read project context**\n - 按优先级查找项目根目录的上下文文件：`ITERATE.md` → `CLAUDE.md` → `PROJECT.md` → `README.md`。\n - 提取项目名、架构、技术栈、代码规范、审查注意点；若都不存在，使用简要描述。\n - 构造 `projectContext` 字符串供后续使用。\n - 绝不读取 `.env`、`.env.*`、`*.{key,pem,p12,crt,cer}`、`credentials.json`、`.aws/`、`.ssh/` 等敏感文件。\n\n7. **创建隔离环境 / Create isolated environment**\n - 检查 `git status` 与是否存在未解决冲突。\n - **优先 worktree 隔离**：若工作区存在未提交改动/未跟踪文件，**优先用 `git worktree add` 创建隔离工作树**进行迭代，**不要求也不强制**用户 commit/stash，也不改动当前脏工作区；迭代结束返回主工作区。\n - 仅当无法创建 worktree（如磁盘/路径受限）且工作区不干净时，才询问用户是否 commit/stash；用户拒绝/取消则**说明原因并建议改用 worktree 方式，而非直接中止**。\n - 存在未解决冲突时提示用户先解决，但不强行中断；可在干净的 worktree 中继续。\n - 记录当前分支名，作为迭代结束后的返回目标。\n - 创建迭代分支：`iterate/-`（或对应 worktree 分支）。\n - 若分支/worktree 创建失败（如名称冲突），尝试追加递增序号后重试，最多 3 次；仍失败则中止并告知用户。\n\n8. **初始化决策日志 / Initialize decision log**\n - 在隔离环境根目录创建 `.iterate_decisions.md`，写入文件头。\n - Initialize `deferredArchitectural = []` for cross-round carry-over.\n\n---\n\n## Step 2 — 迭代循环 / Iteration Loop\n\n```\nround = 1\nwhile round <= maxRounds:\n```\n\n### 纯审查模式 / review-only (dry-run) loop\n\n当调用参数含 `review-only` 或 `dry-run` 时，**跳过 Step 1 中的 git 隔离、跳过所有修复与验证**，只执行只读审查循环并产出最终审查报告。此模式**绝不修改任何文件、绝不创建分支/worktree、绝不调用 fixer**：\n\n```\nphase plan → 获取审查计划（维度、reviewer prompt、findings schema、round cap）\nknownAng = [] → 跨轮累计已发现 findings（供 reviewer 只找新问题）\nrounds = [] → 原始每轮 findings\nfor r in 1..cap:\n # 每个维度一个并行 reviewer，只报 NEW 问题\n raw = parallel(每个维度 → review 该维度, 已知 = knownAng)\n rounds.push({ round: r, findings: raw })\n knownAng.push(...raw)\n # 确定性收敛判定：aggregate 后本轮新 findings 数\n conv = aggregate(rounds) # 汇总去重/排序/每轮新发现数\n if conv.findingsByRound[r-1] == 0: break # 收敛\nphase report → finalReport = aggregate(rounds) # 最终审查报告\nphase meta-review → metaReview = meta-review(finalReport) # 审查报告本身：校验内部一致性\nreturn { rounds, converged, findingsByRound, totalFindings, bySeverity, byDimension,\n report: finalReport,\n metaReview: { verdict, issues, checksRun },\n finalReport }\n```\n\n纯审查模式要点 / review-only key rules:\n- **绝不修改文件**：reviewer 只读项目，所有 aggregate / meta-review 均为纯计算。\n- **收敛驱动**：每轮把已知 findings 喂给 reviewer，迫使其只找新问题；某轮 0 新 findings 即收敛停止；否则到 cap。\n- **产出三级**：① 审查报告（findings + 收敛统计 + 修复优先级建议）；② **meta-review**（审查报告内部一致性：`COUNT_MATCH`/`SEVERITY_SUM`/`DIMENSION_SUM`/`SORT_ORDER`/`CONVERGENCE`/`ROUND_SHAPE`）；③ **最终审查报告**（带 `approved` / `needs_revision` 判定）。\n- 硬证据门禁（`reviewer.evidence_validation`，默认开启）：meta-review 会逐条校验 finding 的 `file`/`line` 是否真实存在于磁盘代码中。任何伪造路径或越界行号都会作为 critical 的 `EVIDENCE_VIOLATION` 浮出并把裁决翻转为 `needs_revision` —— 子代理只允许锚定实际读过的真实代码，禁止推测。\n- 本模式不写入 `.iterate_decisions.md`（除一条 `report` 记录外），不产生任何 git 提交。\n\n### 进度反馈 / Progress Feedback\n\n迭代为多轮长任务，**必须**在与用户的对话中持续输出进度，避免长时间静默造成\"卡住\"观感。主模型遵循以下约定（写在与用户的对话里，而非仅记录到 `.iterate_decisions.md`）：\n\n- **每轮开始**：输出 `▶ Round {N}/{maxRounds} — 启用的维度：{enabled dims}`，并简述本轮范围（涉及模块）。\n- **Phase 1 并行审查期间**：若预计耗时较长，逐维度输出 `⏳ 正在审查 {dimension}（{i}/{total}）…`，让用户看到推进而非无响应。\n- **每轮结束**：输出 `✅ Round {N} complete — 原子修复 x / 架构修复 y / 剩余 findings z`（或本轮失败原因）。\n- **提前终止**：出现 0 findings 时明确输出 `✅ 0 findings，迭代完成` 并说明停止原因。\n- 任一步骤若预计无可见输出超过合理时间，主动补一句进度说明。\n\n### Phase 0 — 维度规划 / Dimension Planning\n\n**仅在第 1 轮执行**。根据用户当次调用 `/iterate` 的 goal 内容，按以下**优先级**解析本轮维度方案：\n\n**① goal 为空或泛化**（如 \"improve code quality\"）→ 直接使用 `iterate.config.yaml` 中的 `dimensions`，不增加摩擦。\n\n**② goal 指定具体范围，且命中已配维度集**（范围路由 / Scope routing）：\n1. 读取 `iterate.config.yaml` 的 `dimension_sets`（可同时参考 `ITERATE.md`「推荐审查蓝图」区）中的命名集。\n2. 将 goal 范围与命名集名匹配（如 \"前端 / 改 UI / 页面样式\" → `frontend`；\"API layer / 接口\" → `api`；\"Security audit / 安全审计\" → `security`）。\n3. 命中命名集 → 本轮直接采用该集的 `dimensions` 及对应的 `focus` 覆盖，**不重定义**；用 `AskUserQuestion` 简要确认后即可进入 Phase 1。\n4. 用户显式指定使用预设维度（如 \"use default dimensions\" / \"按预设审查\"）→ 用全局 `dimensions`，跳过路由。\n\n**③ goal 指定范围，但未命中任何命名集**（偏门范围 → on-the-fly **重定义**）→ 该范围没有任何现成蓝图。**一旦进入重定义，就假设「预设完全不可用」，禁止把全局 `dimensions` 或任一已有维度集当作起点来筛选/微调**——否则那只是伪重定义（多半是你偷懒套预设的结果）。必须从根为该范围重新推导：\n1. **脱离预设，从根推导**：先想清该 goal 的实质——涉及哪些模块/文件、最容易**在这类改动上出错的风险是什么**。基于此推导，从**维度全集**（9 个 canonical：`correctness / security / performance / architecture / style-tests / tech-debt / spec-compliance / frontend-backend / ui-ux`）中重新选择真正相关的维度，**不受全局已启用维度限制**；确有需要时新增非标准临时维度。第 1 步不要打开 `dimensions` 或任何 `dimension_sets` 作为参照。\n2. **强制写出取舍理由**：对选中的每个维度必须给出**本范围特有**的取舍理由（它为何在本范围必要、侧重点与其他范围有何不同），并据此设置针对性的 focus。**凡理由与该范围无关、或与某一预设集雷同，即视为套用预设，必须推翻重想**，直到每个维度都能独立论证。\n3. 将维度 + focus 组装为方案，用 `AskUserQuestion` 请求用户确认，并明确标注这是 **「全新重定义」而非「路由到预设」**。\n4. 用户确认 → 本轮采用重定义方案；用户拒绝 → 回退到全局默认 `dimensions`。\n\n**有界记录（/ Bounded persistence — 解决迭代信息膨胀）**：\n- 预设命名维度集的定义**只存**于 `iterate.config.yaml` 的 `dimension_sets`（结构性配置）。`ITERATE.md` 仅在 AI 维护区渲染**一次**「推荐审查蓝图」清单，**不随轮次增长**。\n- ③ 的临时重定义**仅**在 `.iterate_decisions.md` 当轮 Round 段的专用小节\n `### Scope Dimension Redefinition (on-the-fly)` 记录（格式见决策日志模板）：须写 `**Origin scope:**`，\n 并为每个重定义维度表格行给出**本范围特有的 Independent reason**，不得照抄\n `config/dimensions/.yaml` 的默认 focus（`scripts/validate.py decisions` 会据此做机器校验）。\n 该记录**不写回** `iterate.config.yaml`，也**不追加**进 `ITERATE.md`。当次迭代结束后该临时方案即失效，\n 后续再遇相同偏门范围应重新路由，而非沿用陈旧记录。\n- `ITERATE.md` 的 AI 维护区在 refresh 时只保留**最新快照**；各轮次过程记录一律落在 `.iterate_decisions.md`。当 `.iterate_decisions.md` 超过阈值时，可将最旧轮次归档（压缩为一行摘要）或将已收敛结论提炼进 `ITERATE.md` 的知识快照后清空历史段，从根本上避免任何知识库文件无限膨胀。\n\n> Dimension Planning 只调整维度的 focus prompt 与启用列表（或路由到命名维度集），不改变 atomic/architectural 分类标准、git 隔离、验证流程等核心机制。\n\n### Phase 1 — 并行审查 / Parallel Review\n\n启动 **N 个并行审查子代理**（N = 启用的 dimensions 数量，默认 9），每个审查一个维度。\n\nLaunch **N parallel reviewer sub-agents** (N = enabled dimensions count, default 9), one per dimension.\n\n#### 可用审查维度 / Available Review Dimensions\n\n以下维度可通过 `dimensions` 列表启用或禁用（默认 9 个）。每个维度的中文名、英文名、优先级和 focus prompt 定义在 `config/dimensions/.yaml` 中；`config/dimensions.yaml` 保留为聚合兼容文件。\n\n| 维度 / Dimension | 优先级 / Priority | 关注点 / Focus |\n|------------------|-------------------|---------------|\n| correctness | critical | 崩溃风险、逻辑错误、竞态条件、类型不匹配、静默吞错 |\n| security | critical | 注入、路径遍历、硬编码密钥、输入校验、权限提升 |\n| performance | high | N+1 查询、主线程阻塞、循环引用、O(n²)、启动瓶颈 |\n| architecture | high | 模块边界违规、循环依赖、God Object、缺失抽象 |\n| style-tests | medium | 函数 >80 行、圈复杂度 >15、嵌套 >3、魔法数字、缺失测试 |\n| tech-debt | medium | TODO/FIXME/HACK、废弃 API、临时方案、硬编码配置 |\n| spec-compliance | high | 对照 specs/ 目录，发现未实现功能、规范偏离 |\n| frontend-backend | high | API/RPC 一致性、数据字段、错误传播、事件流覆盖 |\n| ui-ux | medium | 加载/空/错误状态、导航、响应式断点、无障碍 |\n\n每个子代理的任务提示：\n\n```text\nReview the codebase for {DIMENSION} issues ONLY.\n\nScope: {review.scope}\n- \"full\" → review the ENTIRE codebase.\n- \"changed-only\" → review ONLY files changed in the current round (git diff against {git.target_branch}).\n- 当 `review.scope` 为 `changed-only` 且本轮相对于 `target_branch` 无改动文件时，自动 fallback 为 `full`。\n\nEVIDENCE RULE (mandatory): read every file you report on with the read_file tool\nBEFORE judging it. You must NEVER report a location you did not actually read —\nspeculation about code you never inspected is a disqualifying failure, and\nfabricated line numbers are treated as poisoned evidence. Anchor every finding\nto real, read code.\n\nCOVERAGE RULE (mandatory): below is the exact file inventory you are assigned\nto review. You MUST open EVERY file in this inventory with the read_file tool\nbefore judging it — do not skip, skim-declare, or assume any file without\nreading it. Files you did not actually open are considered un-reviewed and\nwill lower your coverage score. Return a `readFiles` array listing every file\nyou actually opened.\n\nAssigned file inventory: {assignedFileInventory}\n\nFocus: {focus description}\n\nProject context: {projectContext}\n\nFor each finding, report:\n- file, line (REQUIRED positive integer for anchored, line-targeted issues —\n the exact line you READ; use 0 for whole-file/module-level issues),\n severity (critical/high/medium/low)\n- dimension, summary, failure_scenario, suggested_fix\n- is_atomic (boolean): true if fix is ≤{atomic.max_lines} lines within a SINGLE function/file;\n false if cross-file, new files, API changes, or large refactoring.\n\nReturn strictly as JSON: { \"findings\": [...], \"readFiles\": [...] }\nEach finding object must contain: file, line, severity, dimension, summary, failure_scenario, suggested_fix, is_atomic.\n`readFiles` must list every file in the assigned inventory you actually opened with read_file.\nIf no issues are found, return { \"findings\": [], \"readFiles\": [...] }.\n```\n\n> **个性化维度 focus / Personalization dimension focus**：若 `personalization.dimension_focus` 中存在当前维度的条目，将其 `focus` 文本追加到上述 prompt 的 `Focus:` 段之后，例如：\n> ```\n> Focus: {focus description}\n> \n> Extra focus (from personalization): {personalization.dimension_focus[dimension].focus}\n> ```\n\n#### 工具映射 / Tool Mapping\n\n| 工具 / Tool | Trae | Claude Code | Cursor / Generic |\n|-------------|------|-------------|------------------|\n| 并行审查子代理 | `Task` × N (type: `search` or `general_purpose_task`) | `Workflow` / `Agent` × N | 手动或脚本并行运行 |\n| 按目录拆分审查 | `Task` per directory/module | `Agent` per directory/module | 脚本分组 |\n| 结果汇总 | `Task` (type: `general_purpose_task`) | `Agent` synthesize | 人工汇总 |\n| reviewer 输出 schema 校验 | 主模型 JSON parse + field check | 主模型 JSON parse + field check | 脚本校验 |\n| 用户审批 | `AskUserQuestion` | `EnterPlanMode` / `ExitPlanMode` | 对话确认 |\n| 文件编辑 | `Read` / `Edit` / `Write` | `Read` / `Edit` / `Write` | IDE 编辑 |\n| 执行命令 | `RunCommand` | `Bash` | Terminal |\n| 配置校验 | `python scripts/validate.py config ...` | `python scripts/validate.py config ...` | 同左 |\n\n#### 支持的 AI 助手与安装路径 / Supported Assistants\n\n使用 `scripts/install.py install --ai --target ` 即可安装到对应目录：\n\n| AI 助手 / Assistant | 安装路径 / Install Path |\n|---------------------|------------------------|\n| Trae | `.trae/skills/iterate/` |\n| Claude Code | `.claude/skills/iterate/` |\n| Cursor | `.cursor/skills/iterate/` |\n| Windsurf | `.windsurf/skills/iterate/` |\n| GitHub Copilot | `.github/skills/iterate/` |\n| OpenAI Codex | `.codex/skills/iterate/` |\n| Roo Code | `.roo/skills/iterate/` |\n| Qoder | `.qoder/skills/iterate/` |\n| Gemini CLI | `.gemini/skills/iterate/` |\n| OpenCode | `.opencode/skills/iterate/` |\n| Continue | `.continue/skills/iterate/` |\n| Augment | `.augment/skills/iterate/` |\n| Warp | `.warp/skills/iterate/` |\n\n安装脚本会自动复制 `SKILL.md`、配置、维度定义、校验脚本和模板到对应目录；`--ai all` 一次性安装到所有支持的助手目录。\n\n常用 CLI 选项（`scripts/install.py`，均需与子命令搭配）：\n- `install --ai |all`：指定安装目标；**非交互（管道/CI）下必填**，否则无法提问。\n- `install --force`：覆盖已存在的 skill 文件。\n- `install --global`：安装到用户主目录（如 `~/.trae/skills/iterate/`），供所有项目复用。\n- `install --dry-run`：只打印将要拷贝的内容，不落盘。\n- `install --target `：指定安装根目录（默认当前项目）。\n- `uninstall --yes`：卸载已安装的 skill；不加 `--yes` 时会要求二次确认。\n- `update --yes`：从 GitHub 最新 release 下载源码刷新文件，跳过确认；**非交互（管道/CI）下必填**，否则会以\"检测到非交互 stdin\"退出 1。\n- `update`（不带 `--yes`）：同上，但交互确认；下载失败时回退到本地源码。\n- `--list` / `--interactive`：列出支持的助手 / 进入交互选择。\n\n#### 按模块/目录拆分 / Split by Module or Directory\n\n当项目较大时，可将一个维度拆分为多个子任务，每个任务只审查一个模块或目录：\n\n```text\nSplit dimension {DIMENSION} review by top-level directories.\nFor each directory, launch a reviewer with scope \"changed-only\" or \"full\".\nMerge findings, removing duplicates across directory boundaries.\n```\n\n#### 子代理失败处理 / Sub-agent Failure\n\n若某个 reviewer 子代理失败、超时或返回无效输出：\n\n1. 若输出非严格 JSON 且 `reviewer.output_schema_validation` 为 true，针对该子代理最多重试 2 次，每次在 prompt 中强调返回严格 JSON。\n2. 若仍失败，记录失败原因到 `.iterate_decisions.md`。\n3. 使用 `AskUserQuestion` / 对话确认询问用户：\n - 继续（continue）：忽略该失败，按当前已收集的 findings 继续。\n - 跳过该维度（skip）：该维度本轮不产生 findings。\n - 中止本轮（abort round）：直接退出本轮循环，进入 Phase 4 记录后结束。\n\n> 若选择 skip 或 abort，仍应将失败原因写入决策日志，避免遗漏审查维度。\n\n#### 汇总与分类 / Synthesize and Classify\n\n使用一个汇总子代理：\n\n```text\nSynthesize findings from all reviewers.\n\nGoal: {goal} / Round: {round}\n\nSteps:\n1. PARSE each reviewer output as JSON; if invalid and reviewer.output_schema_validation is true, retry that reviewer up to 2 times.\n2. REMOVE duplicates (same defect, same file → keep most detailed)\n3. REMOVE false positives (clearly wrong or unactionable)\n4. **FILTER known intentional**：若 `personalization.known_intentional` 非空，移除匹配的 findings。匹配规则：finding 的 `file` 与条目的 `file` 相同，且（条目 `line` 为 0，或 finding 的 `line` 与条目 `line` 相同），且 `dimension` 相同。被过滤的 finding 数量记入决策日志。\n5. RE-VALIDATE is_atomic flag for each finding\n6. CLASSIFY into atomic and architectural\n7. SORT each group by severity (critical → high → medium → low)\n8. TRIM each group to 20 max\n\nReturn: { \"empty\": boolean, \"atomic\": [...], \"architectural\": [...] }\n```\n\n停止条件检查：\n\n```text\nif empty AND deferredArchitectural is empty:\n 写入 .iterate_decisions.md: \"Round {round}: 0 findings, iteration complete.\"\n 输出: \"✅ Round {round}: 0 findings, iteration complete.\"\n break\n```\n\n> **注意 / Note**：如果所有 reviewer 都返回空但代码中明显存在问题，主模型应基于自身判断补充 findings。\n\n---\n\n### Phase 2 — 原子问题直接修复 / Atomic Fixes\n\n若存在原子问题：\n\n1. **计划（内部，不中断） / Plan internally**\n - 分析所有原子 findings。\n - 合并对同一文件的修改。\n - 按严重程度和依赖排序。\n - **应用个性化优先级**：若 `personalization.fix_priority_order` 非空，按其指定的维度顺序重新排序（列在前面的维度优先修复），同维度内仍按严重程度排序。\n - 输出简短计划列表告知用户。\n\n2. **顺序执行 / Execute sequentially**\n\n ```text\n for each atomic finding:\n # Protected paths check\n if finding.file matches any pattern in personalization.protected_paths:\n skip this finding, log \"skipped: protected path {finding.file}\"\n continue\n\n # Risk areas check\n if finding.file is under any personalization.risk_areas[].path:\n use AskUserQuestion to get explicit user approval before modifying\n if user declines: skip, log \"skipped: risk area not approved\"\n\n # Forbidden fixes check\n ensure the planned fix does not use any approach in personalization.forbidden_fixes\n if it would: skip, log \"skipped: forbidden fix approach\"\n\n Read target file\n Apply fix using Edit/Write (ensure ≤ atomic.max_lines, single function scope)\n Record completion status\n ```\n\n > **禁区/风险区/禁止方式 / Protected / Risk / Forbidden**：这三项检查在每次修改文件前都必须执行。`protected_paths` 是 glob 模式（如 `legacy/**`），用 `fnmatch` 或等价方式匹配。`risk_areas` 路径是目录或文件前缀匹配。`forbidden_fixes` 是字符串描述，AI 判断修复方式是否匹配。\n\n3. **验证原子修复 / Validate atomic fixes**\n\n 根据改动的模块跑对应检查（从 `validation.commands` 读取，键名为示例）：\n\n - 确定本轮修改涉及的模块集合：根据修改文件的路径、扩展名或目录结构匹配 `validation.commands` 中的模块键名。\n - 若改动涉及多个模块，依次执行每个模块对应的命令列表。\n - 若某模块未在 `validation.commands` 中配置命令，跳过并提示用户补充配置。\n - 任一模块验证失败即停止后续检查，进入失败处理流程。\n\n 示例 / Examples：\n\n - `python/`：`ruff check src/ && mypy src/ --ignore-missing-imports && pytest tests/ -x -q --timeout=60`\n - `swift/`：`swift build -c debug`\n - `typescript/`：`npm run compile`\n\n 执行前遵循统一运行时白名单语义：只执行 `validation.commands.` 中**显式配置的精确命令**（不自行拼装、不基于前缀构造命令）；未配置命令的模块跳过。`validation.command_whitelist` 仅为配置期校验辅助字段（见下方 Security 章节），可缺省、无运行时约束力——即便未配置，运行时仍以 `validation.commands` 为唯一权威白名单，不在其中的命令**直接拒绝，不可通过用户确认绕过**。\n\n 若验证失败：\n - 追加 `.iterate_decisions.md`：`Atomic fix validation failed: {details}`\n - 输出：`❌ Round {round}: atomic fix validation failed, stopping iteration`\n - **回滚本轮所有原子修改**：`git restore --staged --worktree .`（非破坏性回滚，恢复暂存区和工作区到 HEAD 状态）。**仅限 `iterate/*` 分支执行**（仍在迭代分支上，不影响 main/master）。\n - 将本轮已识别但未执行的架构问题保留在 `deferredArchitectural` 中，供下次 `/iterate` 会话处理。\n - `break`\n\n---\n\n### Phase 3 — 架构问题修复 / Architectural Fixes\n\n若存在架构问题（含 `deferredArchitectural`）：\n\n1. **文件碰撞检测 / File conflict detection**\n - 收集 Phase 2 修改过的所有文件。\n - 对每个架构 finding，检查其文件是否与原子修复文件重叠。\n - 重叠 → 移入 `deferredArchitectural`（下一轮处理）。\n - 不重叠 → 移入 `executableArchitectural`。\n\n2. **分组与排序 / Group and sort**\n - 按模块依赖顺序排序（先被依赖，后依赖者）。\n - 合并同一模块/文件组的 finding 为一个 task。\n - 检测 `executableArchitectural` 内部 task 之间的文件重叠；如有重叠，按依赖顺序拆分为串行 task 或合并为单一 task。\n - 最终确保不同 task 之间的文件集互不重叠。\n\n3. **用户审批 / User approval** — **强制门禁 / Mandatory gate**\n\n > **安全约束 / Security constraint**：架构修复**必须**经用户显式批准后方可执行。此门禁不可跳过、不可自动绕过。即使用户在配置中启用了 `auto_merge: true`，架构修复的审批仍然独立于 merge/push 流程，必须单独获得用户确认。\n\n 呈现给用户：\n\n ```text\n 可执行的架构修复 / Executable architectural tasks:\n - {files} | {description} | {severity} | {approach}\n\n 延迟的架构修复 / Deferred tasks:\n - {files} | {description} | {reason}\n\n Approve these {N} architectural fixes?\n ```\n\n - 批准 → 继续执行。\n - 拒绝 → 全部 executable 移入 `deferredArchitectural`，跳到 Phase 4。\n\n4. **串行委派子代理 / Execute serially via sub-agents**\n\n ```text\n for each task in executableArchitectural:\n # Protected paths check (same as Phase 2)\n if any file in task.files matches personalization.protected_paths:\n defer this task, log \"deferred: protected path\"\n\n # Risk areas check (same as Phase 2)\n if any file in task.files is under personalization.risk_areas[].path:\n use AskUserQuestion to get explicit user approval\n if declined: defer, log \"deferred: risk area not approved\"\n\n Use sub-agent with prompt:\n\n \"You are fixing an architectural issue.\n\n Goal: {goal} / Round: {round}\n Project context: {projectContext}\n\n Task: {task description with file paths, findings, approach}\n\n Constraints (from personalization):\n - Forbidden fix approaches: {personalization.forbidden_fixes or 'none'}\n - Do NOT use any of these approaches in your fix.\n\n Workflow:\n 1. Read all affected files, their callers, and callees.\n 2. Apply the fix using Edit/Write tools.\n 3. Report: success/failure, files_changed, summary, notes.\n\n Previous tasks in this round may have changed some files.\n Read files fresh before editing — they may have been modified.\n Do NOT run build/test commands.\"\n\n Wait for completion before starting the next task.\n If a sub-agent fails, log the reason, report it to the user, and ask whether to continue, skip, or abort the round.\n ```\n\n5. **整体验证 / Full validation**\n\n 根据改动模块跑完整验证（同 Phase 2，但覆盖所有改动模块）。\n\n 执行前遵循运行时唯一权威白名单（同 Phase 2）：只执行 `validation.commands.` 中的精确命令。\n\n 若失败：\n - 追加 `.iterate_decisions.md`：`Full validation failed: {details}`\n - 输出：`❌ Round {round}: full validation failed, stopping iteration`\n - **回滚本轮所有修改**（原子 + 已执行架构）：`git reset --mixed iterate/round-{round}-backup && git restore --worktree .`（非破坏性回滚：`--mixed` 移动分支指针但不改工作区，`git restore` 再恢复工作区文件）。**仅限 `iterate/*` 分支执行**（仍在迭代分支上，不影响 main/master）。\n - 将未执行的架构问题保留在 `deferredArchitectural` 中。\n - `break`\n\n---\n\n### Phase 4 — 记录本轮结果 / Record Round Results\n\n追加到 `.iterate_decisions.md`：\n\n- 原子修复列表 + 状态\n- 架构修复列表（已执行 + 延迟 + 原因）\n- 修改范围审计：本轮修改的文件清单、每个文件对应的 task/reviewer、审批状态\n- AI 重要决策\n\n输出：`✅ Round {round} complete`\n\n---\n\n### Phase 5 — 验证、合并、推送 / Validate, Merge, Push\n\n每轮验证通过后：\n\n1. **Backup tag / 备份标签**\n - 在 commit 前为当前迭代分支打标签：`git tag iterate/round-{round}-backup`\n - 若后续需要回滚，可 `git reset --mixed iterate/round-{round}-backup && git restore --worktree .`（非破坏性回滚）。**仅限 `iterate/*` 分支执行**（仅用于迭代分支，不用于 main/master）。\n\n2. **Commit / 提交**\n - `git add `\n - `git commit -m \"fix: iterate round {round} — {brief summary}\"`\n\n3. **Merge / 合并** ⚠️ **高风险动作 / High-risk action**\n - **默认安全 / Secure by default**：`git.auto_merge` 默认为 `false`，即不自动 merge。仅当用户在配置中显式设为 `true` 时才执行以下 merge 步骤。\n - **风险提示 / Risk notice**：若启用自动 merge，回 `target_branch`（通常为 `main`）会将本轮所有修改立即推到主分支历史。建议保持 `auto_merge: false`，改为创建 PR 由人工 review；或为 `main` 启用分支保护。\n - 若 `git.auto_merge` 为 `true`：\n - `git checkout {target_branch}`\n - `git merge iterate/-`\n - 如有冲突，先尝试自动解决；若无法自动解决，**停止合并并询问用户**手动解决或跳过本轮。\n - 冲突解决后重新验证，验证失败则切回迭代分支，**不推进 main/master**。\n - 若 `git.auto_merge` 为 `false`（默认）：\n - 不执行 merge，修改保留在迭代分支上。\n - 可使用 `AskUserQuestion` 询问用户是否在本轮手动 merge 或留到会话结束时统一处理。\n\n4. **Push / 推送** ⚠️ **高风险动作 / High-risk action**\n - **默认安全 / Secure by default**：`git.push_per_round` 默认为 `false`，即不自动 push。\n - **风险提示 / Risk notice**：若启用自动 push，会立即对外可见，且后续轮次会基于已 push 的状态继续迭代。建议保持 `push_per_round: false`，仅在会话结束时一次性 push。\n - 若 `git.push_per_round` 为 `true`：\n - `git push origin {target_branch}`\n - 若被拒绝，先 `git pull --rebase`，解决冲突，重新验证，再 push。\n - push-pull-rebase 循环最多执行 3 次；超过仍失败则停止并告知用户手动处理。\n - **绝不 force-push 到 main/master**。\n - 若 `git.push_per_round` 为 `false`（默认）：\n - 本轮回不 push，只保留本地 merge（若 `auto_merge` 也为 false，则仅保留在迭代分支）。\n - 在最后一轮或会话结束时，一次性 `git push origin {target_branch}`；同样遵循 3 次循环限制。\n\n5. **切回迭代分支 / Switch back**\n - `git checkout iterate/-`\n - 继续下一轮。\n\n6. **记录 / Log**\n - 在 `.iterate_decisions.md` 中记录 backup tag、commit hash、merge 结果、冲突处理。\n\n```\nround += 1\n```\n\n---\n\n## Step 3 — 汇总报告 / Summary Report\n\n迭代结束后输出：\n\n- 总轮数 / Total rounds\n- 停止原因 / Stop reason\n- 每轮原子修复数 + 架构修复数 / Per-round atomic + architectural fix counts\n- 剩余延迟架构问题（如有）/ Remaining deferred architectural issues\n- `.iterate_decisions.md` 路径 / Decision log path\n- 迭代分支名 / Iteration branch name\n\n### 交付指引 / Handoff（改动如何处理）\n\n改动默认保留在迭代分支 `iterate/-`（未启用 `auto_merge` / `push_per_round`）。汇总后**必须**明确告知用户后续操作，不要让用户困惑\"改动去哪了\"：\n\n- 说明：分支名、`.iterate_decisions.md` 路径、以及是否已合并/推送。\n- 给出清晰选项：让用户 **人工 review 后自行合并推送**，或 **询问是否由 AI 代为合并/推送**（此时先 review 差异再执行安全命令）。\n- 若用户希望保留分支以便二次审查，也予以确认，不强行清理。\n\n### 提前终止 / Early Stop\n\n默认在出现 0 findings 时结束。此外，在每轮结束后评估：\n\n- 若剩余 findings 均为 **low** 且目标基本达成，或达到用户明确设定的目标，可询问用户\"是否提前结束本轮迭代\"，避免无谓多轮消耗。\n- 若用户确认提前结束，输出停止原因与交付指引后退出循环。\n\n---\n\n## Git 隔离工作流 / Git Isolation Workflow\n\n**规则 / Rule**：每次 `/iterate` 会话必须在隔离的本地分支或 worktree 中运行。**绝不直接在 main/master 上提交**。合并与推送均为**主动选择（opt-in）**动作：`git.auto_merge` 与 `git.push_per_round` 默认均为 `false`，仅在用户显式启用时才自动 merge/push；未启用时，改动保留在迭代分支，由用户在会话结束时人工 review 后决定合并或推送。\n\n**Why**：\n- 保持主工作区稳定。\n- 每轮都是独立可审查、可回滚的 commit。\n- 远程始终保存最新验证状态。\n\n### 每会话流程 / Per-Session Flow\n\n```bash\n# 1. Setup\ngit status # 确认状态；有未提交改动时优先用 worktree 隔离\ngit checkout -b iterate/- # 或 git worktree add ../ -b iterate/-\n\n# 2. Each round (after validation passes)\ngit add && git commit -m \"fix: iterate round {N} — ...\"\ngit checkout \ngit merge iterate/- # 解决冲突，重新验证\ngit push origin \ngit checkout iterate/- # 继续下一轮\n\n# 3. Session end\n# 确保所有改动已合并推送\n# 可询问用户是否删除已合并的迭代分支\n```\n\n### 会话中断与恢复 / Session Interruption and Resume\n\n若会话因用户关闭、AI 异常或验证失败而中断：\n\n1. 保留当前迭代分支和 `.iterate_decisions.md`，不要删除。\n2. **下次调用 `/iterate` 时，AI 应主动**先读取 `.iterate_decisions.md`（用户无需自行理解该文件），自动提取并简要呈现：\n - 上次的迭代分支名。\n - 已完成的轮数、`deferredArchitectural` 列表。\n - 是否有未 push 的本地 merge。\n - 上次停止时的轮次与剩余 findings 概要。\n3. 基于以上状态，**主动向用户提议**下一步，而非让用户判断：\n - **继续上次会话（resume）**：切回迭代分支，从下一轮继续。\n - **重新开始（restart）**：创建新迭代分支，`deferredArchitectural` 可继承或清空。\n - **仅查看报告**：只输出上次汇总，不继续迭代。\n4. 若上一轮已合并到 main/master 但未 push，在 resume 时先完成 push。\n\n### 护栏 / Guardrails\n\n- 循环中绝不直接提交到 main/master。\n- 绝不 force-push 到 main/master。\n- Push 被拒绝时，先 `git pull --rebase`，解决冲突，重新验证，再 push。\n- 若某轮验证失败，**不要合并该轮**，留在迭代分支上并告知用户。\n\n---\n\n## 决策日志格式 / Decision Log Format\n\n文件路径：`.iterate_decisions.md`\n\n```markdown\n# Iterate Decision Log\n\nGoal: {goal}\nMax rounds: {maxRounds}\nStarted: {timestamp}\nBranch: {iteration-branch}\n\n---\n\n## Round {N} — {timestamp}\n\n### Atomic Fixes (Direct)\n| # | File | Summary | Severity | Status |\n|---|------|---------|----------|--------|\n| 1 | x.swift | Fix null pointer | high | ✅ |\n\n### Architectural Fixes (Approved + Executed)\n| # | File(s) | Summary | Severity | Status |\n|---|---------|---------|----------|--------|\n| 1 | y.swift, z.swift | Unified error handling | critical | ✅ Executed |\n\n### Architectural Fixes (Deferred to Next Round)\n| # | File(s) | Summary | Defer Reason |\n|---|---------|---------|-------------|\n| 1 | a.swift, b.swift | Refactor data flow | File conflict with atomic fix |\n\n### Reverted Fixes\n| # | File(s) | Summary | Revert Reason |\n|---|---------|---------|---------------|\n| 1 | shared/error_codes.json | Merge v1 codes | Conflict with authoritative v2.0 numbering |\n\n### AI Important Decisions\n| # | Decision | Reason |\n|---|---------|--------|\n| 1 | Merged 5 findings into 1 task | Same module |\n\n### Validation\n- ruff check src/ → 0 errors\n- mypy src/ → Success\n- pytest tests/ → 2600 passed, 0 failed\n```\n\n---\n\n## Skill 目录结构 / Skill Directory Layout\n\n一个完整的 iterate skill 目录应包含以下文件（相对 `SKILL.md` 的路径固定）：\n\n```text\niterate/\n├── SKILL.md # 技能入口与使用说明\n├── pyproject.toml # Python 包定义（iterate CLI entry point）\n├── config/\n│ ├── iterate.config.yaml # 默认配置\n│ ├── config.schema.json # iterate.config.yaml 的 JSON Schema\n│ ├── dimensions.yaml # 聚合版维度定义（兼容旧版）\n│ └── dimensions/ # 数据驱动的维度定义\n│ ├── correctness.yaml\n│ ├── security.yaml\n│ ├── performance.yaml\n│ ├── architecture.yaml\n│ ├── style-tests.yaml\n│ ├── tech-debt.yaml\n│ ├── spec-compliance.yaml\n│ ├── frontend-backend.yaml\n│ └── ui-ux.yaml\n├── iterate_cli/ # iterate CLI 包（onboarding 命令行工具）\n│ ├── __init__.py\n│ ├── __main__.py # python -m iterate_cli 入口\n│ ├── cli.py # argparse 子命令（onboard/refresh/reonboard/status/doctor/…）\n│ ├── tui.py # 轻量 TUI 助手（skills.sh 风格输出、banner）\n│ ├── fingerprint.py # manifest 哈希与漂移检测\n│ ├── scan.py # 项目扫描（技术栈/目录/特性检测）\n│ ├── wizard.py # CLI 交互式 onboarding 向导\n│ ├── generator.py # ITERATE.md + iterate.config.yaml 生成器\n│ ├── refresh.py # 增量刷新与完整重 onboarding\n│ ├── doctor.py # 项目健康诊断（doctor 子命令）\n│ ├── guard.py # 防御式编程校验（guard pre/post-check、invariant 子命令）\n│ ├── personalize.py # 个性化约束管理（personalize 子命令）\n│ ├── show.py # 只读展示生效配置与个性化状态（show 子命令）\n│ └── data/\n│ ├── ITERATE.template.md # 模板副本（随包分发）\n│ └── config.schema.json # schema 副本（随包分发，与 config/ 保持同步）\n├── scripts/\n│ ├── install.py # CLI：安装、卸载、配置、校验\n│ ├── update_downloads_badge.py # 拉取三平台下载量并写 badges/downloads.json\n│ ├── validate.py # 配置、决策日志、维度校验脚本\n│ └── requirements.txt # 校验脚本依赖\n├── templates/\n│ ├── iterate-decisions.template.md # 决策日志模板\n│ ├── ITERATE.template.md # 项目知识库模板（分区：AI 维护 + 用户维护）\n│ └── onboarding-playbook.md # AI onboarding 参考映射（仅供参考）\n├── tools/\n│ ├── SKILL.trae.md # Trae 专属 prompt/workflow 示例\n│ ├── SKILL.claude.md # Claude Code 专属 workflow 示例\n│ └── SKILL.cursor.md # Cursor 专属 prompt 示例\n├── tests/\n│ ├── test_dimension_lock.py # 六源维度系统一致性锁定（skill ↔ harness）\n│ ├── test_doctor.py # doctor 项目健康诊断测试\n│ ├── test_drift_ignore.py # 漂移忽略与 status 漂移建议测试\n│ ├── test_guard.py # 防御式校验（guard / invariant）测试\n│ ├── test_install_script.py # install.py 安装脚本测试\n│ ├── test_onboarding.py # onboarding 模块测试\n│ ├── test_refresh_reconcile.py # refresh 对账测试\n│ ├── test_tui.py # TUI 渲染器接口契约测试\n│ ├── test_update_downloads_badge.py# update_downloads_badge.py 测试\n│ └── test_validate.py # 校验脚本测试\n└── README.md / CONTRIBUTING.md # 用户与贡献者文档\n```\n\n运行时优先读取**项目根目录**的 `iterate.config.yaml`；若不存在，则使用 skill 目录下的 `config/iterate.config.yaml` 作为默认配置。校验脚本路径以 `${CLAUDE_SKILL_DIR}/scripts/validate.py`（Claude Code）或 skill 安装目录相对路径解析。\n\n---\n\n## 配置说明 / Configuration\n\n默认配置见 [`config/iterate.config.yaml`](./config/iterate.config.yaml)。\n\n| 配置项 / Key | 类型 / Type | 默认值 / Default | 说明 / Description |\n|--------------|-------------|------------------|--------------------|\n| `goal` | string | `\"Improve code quality and maintainability\"` | 迭代目标 |\n| `max_rounds` | int | `7` | 最大轮数 |\n| `language` | string | `\"en\"` | 输出语言 `zh` / `en` |\n| `mode` | string | `\"iterate\"` | 本次调用默认模式：`iterate`（原模式）/ `defensive`（防御式编程模式）；可用调用参数 `defensive` 显式覆盖（v3.0） |\n| `invariants.ensure` | list | `[]` | 项目级不变量：收尾时必须存在的文件路径断言（相对项目根，`iterate invariant` 校验，v3.0） |\n| `invariants.commands.` | list | `[]` | 项目级不变量：收尾时必须通过的命令列表（精确匹配、走安全基线；无 `invariants` 段时 `iterate invariant` 退化为 `validation.commands`，v3.0） |\n| `dimensions` | list | 全部 9 维度 | 启用的审查维度 |\n| `review.scope` | string | `\"full\"` | 审查范围：`changed-only` / `full` |\n| `atomic.max_lines` | int | `20` | 原子问题行数上限 |\n| `atomic.max_adjacent_methods` | int | `3` | 相邻方法数上限 |\n| `git.target_branch` | string | `\"main\"` | 合并目标分支 |\n| `git.use_worktree` | bool | `false` | 是否默认使用 worktree；**当工作区有未提交改动/未跟踪文件时，无论此值如何，都优先用 worktree 隔离**（见 Step 1.7） |\n| `git.push_per_round` | bool | `false` | 每轮通过后是否立即 push（默认 false，安全） |\n| `git.auto_merge` | bool | `false` | 每轮验证后是否自动 merge 回 target_branch（默认 false，安全） |\n| `validation.command_whitelist` | list | 常见命令前缀 | 配置期校验辅助字段（可选、可缺省）：`scripts/validate.py` 据此检查 `validation.commands` 各命令以合理工具前缀开头；无运行时约束力，运行时以 `validation.commands` 为唯一权威 |\n| `validation.commands.` | list | 示例命令 | 各模块验证命令；**运行时唯一权威白名单**，AI 只执行其中的精确命令，不自行拼装或基于前缀构造命令 |\n| `reviewer.output_schema_validation` | bool | `true` | 是否校验 reviewer JSON 输出并自动重试 |\n| `reviewer.evidence_validation` | bool | `true` | 硬证据门禁：meta-review 校验每个 finding 的 file/line 真实性，伪证判 `needs_revision` |\n| `reviewer.coverage_validation` | bool | `true` | 范围覆盖率校验（提示性）：自报 `readFiles` 明显不覆盖分配清单时浮出 `COVERAGE_GAP`，不反转判定 |\n| `reviewer.scope_chunk_size` | int | `25` | `full` 审查每批分配的文件数，按此拆分 reviewer 任务 |\n| `personalization.protected_paths` | list | `[]` | 禁区 glob 模式，iterate 不得修改 |\n| `personalization.risk_areas` | list | `[]` | 风险区（path + reason），改动需用户审批 |\n| `personalization.known_intentional` | list | `[]` | 已知意图（file:line + dimension），Phase 1 过滤误报 |\n| `personalization.dimension_focus` | list | `[]` | 维度定制（dimension + focus），追加到 reviewer prompt |\n| `personalization.fix_priority_order` | list | `[]` | 修复优先级顺序（从高到低） |\n| `personalization.forbidden_fixes` | list | `[]` | 禁止的修复方式（如 `# noqa`） |\n\n> **个性化配置由 `iterate onboard` 或 `iterate personalize` 写入**，捕获 AI 扫描不到的项目专属约束。详见 README 中的\"个性化配置 / Personalization\"章节。\n| `onboarding.version` | string | `\"1.0\"` | 指纹 schema 版本 |\n| `onboarding.completed_at` | string | — | 上次 onboarding/刷新的 ISO 8601 时间戳 |\n| `onboarding.channel` | string | — | onboarding 通道：`cli` / `ai` |\n| `onboarding.drift_check` | bool | `true` | 是否在每次调用时检查 manifest 漂移 |\n| `onboarding.drift_ignore` | list | `[]` | 漂移忽略的 manifest glob 模式（如 `package-lock.json`），命中文件不计入漂移 |\n| `onboarding.f\n\nFile v3.4.4:npm-installer/README.md\n\n# iterate-skill-installer\n\n

\n English ·\n 简体中文\n

\n\nOne-command installer for [iterate-skill](https://github.com/jingzhao-l/iterate-skill) across AI coding assistants.\n\n[![GitHub stars](https://img.shields.io/github/stars/jingzhao-l/iterate-skill?style=social&label=Star)](https://github.com/jingzhao-l/iterate-skill)\n\n> ⭐ If this project helps you, please consider giving a GitHub star — it means a lot to open-source maintenance!\n\n## Usage\n\n```bash\n# Interactive install — detects your AI assistants and lets you choose\nnpx iterate-skill-installer\n\n# Install to a specific assistant only\nnpx iterate-skill-installer --ai trae\nnpx iterate-skill-installer --ai claude\n\n# Install into a project directory instead of globally\nnpx iterate-skill-installer --target ./my-project\n\n# Force overwrite existing skill files\nnpx iterate-skill-installer --force\n\n# Skill-only install — skip installing the iterate CLI\nnpx iterate-skill-installer --no-cli\n\n# Show help / version\nnpx iterate-skill-installer --help\nnpx iterate-skill-installer --version\n```\n\n## What it does\n\n1. Checks for Python 3 on your system.\n2. Fetches the latest iterate-skill release from GitHub.\n3. Downloads the release tarball and `SHA256SUMS.txt`.\n4. Verifies the tarball checksum.\n5. Extracts the release into a temporary directory.\n6. Runs the bundled Python install script (`scripts/install.py`) which:\n - Detects installed AI coding assistants on your machine.\n - Prompts you to select targets (default: all detected assistants).\n - Copies the skill files into the correct skills directories.\n7. Installs the `iterate` CLI onto your PATH (prefers `pipx`, otherwise\n `pip install --user`) so you can run `iterate onboard` directly.\n\n> **Note:** the installer normally puts the `iterate` CLI on your PATH so a single\n> command gives you both the skill and the CLI. If you **don't** want the CLI\n> auto-installed, pass `--no-cli` to install the skill only — you can install the\n> CLI later with `pipx install .` or `pip install .` from a checkout. If the CLI\n> install fails, you can still install it later the same way.\n\n## Supported AI assistants\n\nTrae, Claude / Claude Code, Cursor, Windsurf, GitHub Copilot, Codex, Gemini CLI, OpenCode, Aider, AiderDesk, Zed, Warp, Continue, Cline, Roo Code, Qoder, Augment, OpenClaw, Autohand Code CLI, IBM Bob, CodeArts Agent, Antigravity, Amp, Deep Agents, Kimi Code CLI, Astral.\n\n## Requirements\n\n- Node.js 18+\n- Python 3.10+\n- `tar` command available on PATH (available by default on macOS, Linux, Windows 10+)\n\n## Release tarball structure\n\nThe GitHub release asset `iterate-skill.tar.gz` must contain **exactly one\ntop-level directory** (e.g. `iterate-skill/`). The installer extracts it with\n`tar --strip-components=1`, so a tarball with multiple top-level directories,\nor with entries whose path disappears after stripping the top level, is\nrejected instead of being silently mis-extracted.\n\n## License\n\nMIT\n\nFile v3.4.4:README.md\n\n# Iterate Skill\n\n> **English** · [简体中文](./README.zh-CN.md)\n\n
\n A portable, configurable AI coding assistant skill: fully automated multi-round code review and fixing.\n
\n\n
\n\n

\n \n \"Total\n \n

\n\n

\n \"ClawHub\"\n \"SkillHub\"\n \"npm\"\n \"License\"\n \"GitHub\n \"GitHub\n

\n\n> Want to support this project? A GitHub **Star** is the best thank-you and helps more developers discover iterate.\n\n---\n\n## Table of Contents\n\n- [About This Project](#about-this-project)\n- [At a Glance](#at-a-glance)\n- [Quick Start](#quick-start)\n- [Installation](#installation)\n- [Usage](#usage)\n- [CLI Command Reference](#cli-command-reference)\n- [How It Works](#how-it-works)\n- [Configuration](#configuration)\n- [FAQ](#faq)\n- [Security](#security)\n- [Directory Structure](#directory-structure)\n- [Contributing](#contributing)\n- [Disclaimer](#disclaimer)\n- [License](#license)\n\n---\n\n## About This Project\n\n**iterate** is an open-source project that gives AI coding assistants the ability to perform **multi-round, autonomous code review and fixing**. You don't need any background about an \"iterate\" concept — it solves a very concrete pain point:\n\n> AI assistants often \"talk a lot but do little\": a single conversation touches only a few lines, looks at one file and never re-checks the whole, and rarely re-verifies what it broke. `/iterate` automates these small but critical finishing tasks — item-by-item review, per-dimension triage, fixing, verification, and iteration — so the AI truly finishes a change **completely and correctly**, like a senior engineer.\n\nIts operating mechanism can be summarized as a self-closing pipeline:\n\n```text\nSet the goal → multi-dimension parallel review → atomic fixes + architecture fixes (with your approval) → verify → re-review → iterate until convergence / max rounds → output summary\n```\n\nThe skill keeps evolving through major versions:\n\n- **v2** — deterministic convergence: repeated multi-dimension review until a round finds zero new issues, plus isolated `iterate/*` branches and a decision log.\n- **v3.0** — dual modes: the original `/iterate` review/fix loop stays untouched, and a new **defensive-programming mode** (`/iterate defensive`) covers everyday coding tasks (add features, fix bugs, refactor), hardened by deterministic `iterate guard` pre/post checks and an `invariant` delivery gate.\n- **v3.1** — `iterate fingerprint` for non-blocking manifest-drift verification, a smarter `iterate doctor` that reports how many checks passed, and fail-closed guard semantics.\n\n**iterate is not a standalone tool; it is a skill ecosystem that attaches to your existing AI assistants.** It doesn't replace your IDE or AI tools; instead it adds a strict \"code gatekeeping\" layer to your existing workflow. The ecosystem is made up of three components that share the same configuration and review dimensions:\n\n- **Core Skill + CLI** — a portable AI skill `/iterate` + `iterate` CLI (root of this repo). Multi-round iteration inside the conversational UIs of Trae / Claude Code / Cursor / Copilot / Codex and 25+ assistants.\n- **[iterate-harness](https://github.com/jingzhao-l/iterate-harness)** — a standalone headless engine, command `ih` (source `harness/iterate-harness`, npm: `iterate-harness`). Runs the same closed loop outside a conversational assistant — in the terminal / CI / git hooks.\n- **[iterate-plugin](https://github.com/jingzhao-l/iterate-plugin)** — a dsh desktop-client plugin (source `harness/iterate-plugin`, npm: `iterate-plugin`). Brings iterate's convergence dashboard and review progress into the dsh desktop UI.\n\nThe relationship: the **skill** (this repo's core deliverable) targets conversational iteration in any AI assistant; the **harness** is the same closed-loop engine for headless / CI scenarios; the **plugin** re-plays the harness runtime inside dsh. The configuration (`iterate.config.yaml`) and dimension system are fully consistent across all three — understand one and you can transfer the rest.\n\n**Related project: [GlassPane](https://github.com/jingzhao-l/GlassPane).** The JSON Schema contract layer in [`kernel/`](kernel) (`@iterate/kernel`) is also the language spoken by GlassPane, a runtime verification engine for AI agents on macOS: an agent acts through MCP, and GlassPane returns evidence of whether the claimed UI change actually happened — accessibility-tree and pixel deltas, an attribution verdict, and a checkpoint to roll back to. iterate answers \"is this code right?\"; GlassPane answers \"did that operation really take effect?\". It is a deliberately separate concern: GlassPane does not read `iterate.config.yaml`, and it ships on its own release line.\n\nThe harness and plugin can also be installed and used independently of this repo:\n\n```bash\n# iterate-harness: one-command install (npm wrapper, simplest)\nnpm install -g iterate-harness\n\n# or script install (oh / ohmo have fully migrated to ih)\ncurl -fsSL https://raw.githubusercontent.com/jingzhao-l/iterate-harness/main/scripts/install.sh | bash\nih iterate init && ih iterate review\n\n# iterate-plugin: GitHub install for the dsh desktop plugin\ndsh plugin --profile web add github:jingzhao-l/iterate-plugin#main\n```\n\n> The harness bundles an OrcaRouter gateway provider (including a free model tier). Register via the [referral link](https://www.orcarouter.ai/ref/ref_5eca75a9c809c95ab152) to support the project; see the [iterate-harness README](https://github.com/jingzhao-l/iterate-harness) for setup guidance.\n\n> The rest of this document focuses on the **skill (repo root)** and its most common conversational usage. Full docs for the harness and plugin live in their own repos: [iterate-harness](https://github.com/jingzhao-l/iterate-harness) (source `harness/iterate-harness/README.md`), [iterate-plugin](https://github.com/jingzhao-l/iterate-plugin) (source `harness/iterate-plugin/README.md`).\n\n---\n\n## At a Glance\n\n**Iterate Skill** lets an AI assistant review and fix a codebase over multiple rounds, like a rigorous senior engineer.\n\n- **Dual modes** — `/iterate` is the original multi-round review → fix → converge loop (v2 behavior, zero breakage); `/iterate defensive` is a defensive-programming mode for normal incremental coding tasks, ending in the same iterate convergence gate.\n- **9 dimensions in parallel** — correctness, security, performance, architecture, style-tests, tech-debt, spec-compliance, frontend-backend, ui-ux.\n- **Scope dimension sets** — named `dimension_sets` (e.g. `frontend`, `api`, `security`) preset at onboarding; a scoped goal routes to the matching set, off-catalog scopes trigger an on-the-fly redefinition recorded in `.iterate_decisions.md` (never copied from presets).\n- **Two-track fixing** — atomic issues (≤20 lines, single file) are fixed automatically; architecture issues are fixed only after your approval.\n- **Deterministic gate CLI** — `iterate guard pre-check` / `post-check` + `iterate invariant` — exact, fail-loud checks the host AI runs before/after every edit and at delivery (defensive mode).\n- **Git isolation** — each round runs on an isolated `iterate/*` branch or worktree; merge/push is off by default and must be explicitly enabled.\n- **Secure-by-default** — `push_per_round` and `auto_merge` default to `false`.\n- **Command whitelist** — double validation at config time and personalization time; rejects dangerous shell metacharacters.\n- **Checksum & verification** — enforces SHA256 verification when updating from GitHub Release.\n- **Multi-assistant support** — Trae, Claude Code, Cursor, Windsurf, GitHub Copilot, Codex, Roo Code and 25+ tools.\n- **Project knowledge base** — auto-generates `ITERATE.md` + `iterate.config.yaml`, with drift detection and incremental refresh.\n\n---\n\n## Quick Start\n\n### 1. Install the skill\n\n```bash\nnpx iterate-skill-installer\n```\n\nIt auto-detects your installed AI coding tools and interactively lets you choose which assistants to install into. Use `--ai ` to target a single assistant directly. The installer also installs the `iterate` CLI (for step 2's `iterate onboard`, etc.) — one command installs skill + CLI.\n\n### 2. Enter a project and complete onboarding\n\n```bash\ncd /path/to/your-project\niterate onboard\n```\n\n`iterate onboard` generates your project's knowledge base:\n\n- `ITERATE.md`: tech stack, module map, conventions, forbidden areas, and more\n- `iterate.config.yaml`: iteration goal, review dimensions, validation commands, and more\n\n### 3. Start iterating\n\nIn your AI assistant's conversation, type:\n\n```text\n/iterate \"improve code quality, ensure all functions are ≤80 lines and tests pass\"\n```\n\nOr launch the CLI directly in the terminal:\n\n```bash\niterate status # view onboarding status and drift\niterate refresh # incrementally refresh ITERATE.md\niterate personalize # add project-specific constraints\n```\n\n---\n\n## Installation\n\n### Recommended: one-command npx install (for most users)\n\nNo repo cloning, no manual Python environment setup — one command downloads, verifies, and installs the skill, and also installs the `iterate` CLI:\n\n```bash\n# Auto-detect installed AI assistants and choose interactively\nnpx iterate-skill-installer\n\n# Install only into Trae\nnpx iterate-skill-installer --ai trae\n\n# Install into a specific project directory\nnpx iterate-skill-installer --target /path/to/project\n\n# Force-overwrite a previously installed skill\nnpx iterate-skill-installer --ai trae --global --force\n```\n\nCommon options:\n\n- `--ai ` — install only into a specific assistant, e.g. `trae`, `claude`, `cursor`\n- `--target ` — project-level install into a directory\n- `--global` — install into the user home directory (default)\n- `--force` — overwrite existing skill files\n- `--token ` — GitHub token to raise API rate limits\n- `-h, --help` / `-v, --version` — show help / version\n\n> **The installer puts the `iterate` CLI on your PATH** (prefer `pipx` isolated install, else `pip install --user`) so that `npx iterate-skill-installer` completes \"skill + CLI\" in one command. That does place an executable on your system. If you don't want automatic CLI install, use the \"manually copy SKILL.md\" or \"source scripts\" approaches below instead.\n>\n> The installer requires Node.js 18+ and Python 3.10+. It creates an isolated Python virtualenv, installs dependencies, and calls `scripts/install.py` to copy files. When downloading a release it forces verification against `SHA256SUMS.txt` — install is rejected on mismatch. If the `iterate` command fails to install, you can still install it manually with `pipx install .` or `pip install .`.\n\n### Other install methods\n\nIf you can't use npm, or you want full control over the install, use one of these.\n\n#### Method A: install the iterate CLI locally\n\n`npx` one-command install already installs the `iterate` CLI. If you didn't use npx, or want to install/upgrade the CLI manually:\n\n```bash\ngit clone https://github.com/jingzhao-l/iterate-skill.git\ncd iterate-skill\n\n# Recommended: isolated install with pipx\npipx install .\n\n# or plain pip\npip install .\n\n# verify\niterate --version\n```\n\nAfter install you can use `iterate onboard`, `iterate personalize`, `iterate status`, `iterate refresh`, `iterate reonboard` in any project directory.\n\n#### Method B: manually copy the skill directory\n\n> ⚠️ **You must copy the entire `iterate/` directory, not just `SKILL.md`.** `SKILL.md` resolves `config/`, `scripts/validate.py`, and `templates/` at runtime relative to its install directory. Copying only one file causes `/iterate` to fail because it can't find the config and validation scripts.\n\nIf you don't want to use the npx installer, copy the whole skill directory to the assistant directory:\n\n```bash\n# Clone or download the source first to get an iterate/ dir with SKILL.md, config/, scripts/, templates/\ngit clone https://github.com/jingzhao-l/iterate-skill.git\nSKILL_DIR=$(pwd)/iterate-skill\n\n# Trae\nmkdir -p ~/.trae/skills/iterate\ncp -R \"$SKILL_DIR\"/SKILL.md \"$SKILL_DIR\"/config \"$SKILL_DIR\"/scripts \"$SKILL_DIR\"/templates ~/.trae/skills/iterate/\n\n# Claude Code\nmkdir -p ~/.claude/skills/iterate\ncp -R \"$SKILL_DIR\"/SKILL.md \"$SKILL_DIR\"/config \"$SKILL_DIR\"/scripts \"$SKILL_DIR\"/templates ~/.claude/skills/iterate/\n\n# Cursor\nmkdir -p ~/.cursor/skills/iterate\ncp -R \"$SKILL_DIR\"/SKILL.md \"$SKILL_DIR\"/config \"$SKILL_DIR\"/scripts \"$SKILL_DIR\"/templates ~/.cursor/skills/iterate/\n```\n\nFor more tool paths, see the \"tool mapping table\" in [`SKILL.md`](./SKILL.md).\n\n#### Method C: source scripts (for developers)\n\n```bash\ngit clone https://github.com/jingzhao-l/iterate-skill.git\ncd iterate-skill\n\npython scripts/install.py install --ai trae --global\npython scripts/install.py update --ai trae --target /path/to/project\npython scripts/install.py uninstall --ai trae --target /path/to/project --yes\n```\n\n### Global vs. project-level install\n\n- **Global install** (`~/.trae/skills/iterate/`) — the first `/iterate` invocation triggers onboarding in every project.\n- **Project-level install** (`/project/.trae/skills/iterate/`) — after onboarding it reuses the project root's `ITERATE.md`, no repeated onboarding.\n\nSuggestion: install globally once so the assistant \"gets to know you\"; then do a project-level install in important projects to avoid repeated onboarding.\n\n### Why not skills.sh?\n\nThis project was previously distributed on skills.sh / SkillHub and other platforms. Since v2.1, **`npx iterate-skill-installer` is the recommended unified install method** because:\n\n1. **One command**: auto-download, SHA256 verify, environment prep, assistant selection — no manual cloning or file copying.\n2. **Consistent versions**: always installs from the GitHub Release, avoiding version drift from platform caches.\n3. **Unified across assistants**: one install logic supports 25+ AI assistants instead of each platform maintaining its own.\n4. **Secure & verifiable**: forces verification against `SHA256SUMS.txt`; install is rejected on mismatch.\n\nMarketplace pages like skills.sh remain for display and discovery but are no longer the primary install entry.\n\n---\n\n## Usage\n\n### In an AI assistant\n\nAfter installing the skill, type these into any AI tool that supports it:\n\n```text\n/iterate \"your goal\"\n/iterate \"your goal\" 10\n/iterate \"your goal\" no-limit\n/iterate \"review code quality\" review-only # pure review mode: review repeatedly to zero findings, read-only\n/iterate \"full health check\" --dry-run # pure review alias: review report + meta-review final report\n/iterate defensive \"add user login + fix the payment bug\" # defensive-programming mode (v3.0): from design to delivery\n```\n\nThe first invocation auto-triggers onboarding (if the project has no `ITERATE.md`).\n\n> **Defensive-programming mode (`/iterate defensive`)**: when you want the AI to do **normal incremental coding work** — add features, fix bugs, refactor, wire up an API, add tests — instead of a pure review, use `/iterate defensive`. The host AI carries defensive-programming discipline from start to finish: declare assumptions + run `iterate guard pre-check` before touching code, validate at trust boundaries with minimal steps while editing, run `iterate guard post-check` after every change, and finish with `iterate invariant` plus the full 9-dimension review→fix→converge loop as a **delivery gate**. It does not deliver until everything converges. The original `/iterate` mode (v2) is unchanged.\n\n> **Pure review mode / review-only (dry-run)**: when the invocation contains `review-only` or `dry-run`, this skill does a read-only health check and **never modifies any file**. It repeatedly reviews in parallel until a round yields 0 new findings (convergence), produces a review report, then **reviews that report itself** (meta-review, checking internal consistency) and gives a final report with an `approved` / `needs_revision` verdict. Use it for pre-release health checks, code quality audits, or when you don't want the AI to touch code.\n\n### In the terminal\n\n```bash\n# Interactive onboarding (auto-branches on first/non-first use)\niterate onboard\n\n# Add / view / clear personalization constraints mid-way\niterate personalize # enter the 9-step personalization wizard\niterate personalize --clear # clear all personalization (structured rules + ITERATE.md sections)\niterate personalize --clear --yes # skip confirmation\niterate show # read-only merged config + personalization details (--json for structured output)\n\n# View onboarding status and drift detection\niterate status\n\n# Incremental refresh (keeps hand-written ITERATE.md section)\niterate refresh\n\n# Full re-onboarding (backs up old files)\niterate reonboard\n\n# Verify manifest fingerprints vs the recorded ones (non-blocking drift check)\niterate fingerprint # verify (default): exits 0 = no drift, 1 = added/removed/changed manifests\niterate fingerprint --json # structured JSON output (script-friendly)\n\n# Non-interactive config inspection & editing (no wizard)\niterate config # list all settable values\niterate config get max_rounds # read one resolved value (--json for {\"key\": value})\niterate config set goal \"...\" # validate + write one value (auto timestamped backup)\n\n# Defensive-programming deterministic checks (v3.0 defensive mode)\niterate guard pre-check src/ # before editing: target exists / worktree clean / manifests ready\niterate guard post-check python # after editing: run exactly validation.commands.\niterate invariant # at delivery: file-assertions + exact commands (degrades to validation.commands)\n```\n\n> **Recommended new-user path**: `npx iterate-skill-installer` (install) → `iterate onboard` (init) → `iterate doctor` (optional health check) → `iterate personalize` (optional constraints) → `/iterate \"your goal\"` in your AI assistant, or `iterate status` / `iterate refresh` / `iterate personalize` on the CLI.\n>\n> The first `/iterate` invocation will do onboarding first if the project has no knowledge base — seeing a \"initializing project\" message is normal, not a failure. After that, every round's changes stay on an isolated `iterate/*` branch/worktree; merge/push is off by default and happens after you review.\n\n### Edge Cases\n\n- **Onboarding cancelled mid-way (Ctrl+C / \"skip\")**: no half-finished artifacts. All files are written **atomically** (`tempfile + os.replace`), so nothing is left behind — just re-run.\n- **Hand-written `ITERATE.md` missing `USER-OWNED` markers**: `iterate refresh` (and AI refresh) **refuses to overwrite and errors** instead of destroying your hand-written content. Add `` markers to refresh normally.\n- **Non-git project**: `onboard` / `status` / `refresh` / `doctor` / `personalize` don't depend on git and work directly; but the git-isolated branch/merge/push steps in `/iterate` need a git repo — without one those steps are skipped or prompted.\n- **Empty project / no manifest files**: onboarding generates the knowledge base normally; without fingerprint files like `package.json` / `pyproject.toml`, drift detection skips fingerprint comparison.\n- **Corrupted `iterate.config.yaml` (YAML error / schema violation)**: `iterate status` distinguishes a **present-but-unparsable** config (exit 1, \"could not be parsed\", suggests `iterate doctor`) from a **missing** one (exit 0, \"config not found — only ITERATE.md exists\" hint); `iterate doctor` reports schema errors; `doctor --fix` only fixes safely auto-fixable items, the rest need manual fixing. If config fails schema validation, `/iterate` aborts immediately with an error rather than running with a broken config.\n- **Early convergence**: when a round returns 0 new findings, iteration ends early (Early Stop) instead of running to `max_rounds`.\n\n---\n\n## CLI Command Reference\n\n### iterate doctor (project health diagnostics)\n\n`iterate doctor` checks your project against the skill's own spec to catch drift early. It verifies:\n\n- **Onboarding completeness** — `ITERATE.md` and `iterate.config.yaml` exist\n- **Config parses & is valid** — config parses as YAML and **fully** matches `config/config.schema.json`\n- **Dimensions valid** — `dimensions` only reference one of the 9 spec dimensions\n- **Review scope valid** — `review.scope` allows only `full` / `changed-only`\n- **Merge target branch** — `git.target_branch` is a non-empty string\n- **Validation commands** — `validation.commands` is a non-empty string list\n- **Command whitelist** — `command_whitelist` entries are safe and every command is within the whitelist\n- **Personalization dimension refs** — `personalization` dimension references point to enabled dimensions\n- **Version consistency** — onboarding `skill_version` matches the currently installed skill version\n- **Drift detection** — whether the tech-stack manifest changed since onboarding\n\n```bash\niterate doctor # TUI output; healthy exit 0, problems exit 1\niterate doctor --json # structured JSON to stdout (script-friendly)\niterate doctor --json-out report.json # write JSON report to a file (auto-creates dirs)\niterate doctor --fix # apply safe, non-destructive fixes (auto timestamped backup), then re-run diagnostics\n```\n\n`--fix` only does items that can be safely auto-fixed, and always creates a timestamped backup of `iterate.config.yaml` (`.doctorfix-` suffix) before fixing. Destructive/ambiguous fixes are never applied automatically — they're reported for you to handle manually. Currently auto-fixable: `dimensions` de-dupe/empty-restore-to-default, `language` invalid value reset to `en`, `max_rounds` non-integer removal / out-of-range clamp to `[1, 50]`, `git.target_branch` empty reset to `main`, `onboarding.skill_version` sync to installed version.\n\n### iterate fingerprint (verify manifest drift)\n\n`iterate fingerprint` (default action `verify`) compares the SHA-256 manifest fingerprints recorded at onboarding/refresh time against the current project root, detecting added / removed / changed tech-stack manifests — a non-blocking informational health check. It exits `0` when there is no drift (or drift checking is unavailable), and `1` when drift is detected, making it CI-friendly:\n\n```bash\niterate fingerprint # verify (default): TUI output\niterate fingerprint --json # structured JSON: {\"project\": ..., \"available\": bool, \"drift\": bool, ...}\n```\n\nFingerprints are (re)captured by `iterate onboard` / `iterate refresh` / `iterate reonboard`, and the same check runs silently inside `iterate status` and in the drift-prompt path of each `/iterate` invocation.\n\n### iterate show (read-only merged config & personalization)\n\n`iterate show` read-only displays the current merged project state — handy for quickly checking config and constraints, **writing no files**:\n\n```bash\niterate show # TUI output: onboarding metadata + effective config + personalization + drift status\niterate show --json # structured JSON to stdout (for scripts / CI / quick diff)\n```\n\nWhen you just want to confirm what restrictions are configured (forbidden areas, risk zones, known intent, dimension customization, fix order, notes, code conventions, extra validation commands), or check the merged `validation.commands` / whitelist, `iterate show` is clearer than reading `iterate.config.yaml` + `ITERATE.md` directly.\n\n### iterate personalize --clear (clear personalization)\n\nWhen you need to clear previously configured personalization constraints, do it in one shot after confirmation (structured rules removed from `iterate.config.yaml`, associated extra validation commands cleaned from `validation.commands`, personalization section in `ITERATE.md` user area removed, while keeping your hand-written content):\n\n```bash\niterate personalize --clear # with confirmation prompt\niterate personalize --clear --yes # skip confirmation\n```\n\nIf there is no personalization content, it says \"no personalization to clear\" and exits normally (exit code 0).\n\n### iterate config (non-interactive config get/set)\n\n`iterate config` lets you inspect or change config values without launching the wizard — handy for scripts / CI / quick edits:\n\n```bash\niterate config # TUI: list every settable key + current value\niterate config --json # JSON object of all settable values (stdout stays clean for scripts)\niterate config get max_rounds # print one resolved value; --json -> {\"max_rounds\": ...}\niterate config set language zh # validate + write one value (auto timestamped backup before write)\niterate config set reasoning_effort high --json # confirm object {\"key\": ..., \"value\": ...}\n```\n\nSupports flat keys (`goal`, `max_rounds`, `reasoning_effort`, `language`, `mode`, `dimensions`) and nested segments (`atomic.*`, `git.*`, `review.scope`, `reviewer.*`, `validation.commands`, `invariants.*`). A corrupted config is never overwritten — `set` aborts with a clear error.\n\n### iterate guard (defensive-mode pre/post-edit checks, v3.0)\n\nDeterministic fail-loud checks the host AI runs around every coding step in defensive mode. Contract: exit code 0 = safe to proceed / change is safe; 1 = must fix or roll back.\n\n- `iterate guard pre-check [paths...]` — runs **before editing**: targets exist, git worktree clean, manifest files ready, validation config safe, and each configured validation command's tool is on `PATH` (shell builtins like `true` are allowed) (`PASS`/`FAIL`).\n- `iterate guard post-check [module...]` — runs **after each change**: executes exactly the configured `validation.commands.` (the runtime's single authority whitelist — no composition, no prefixing).\n\nBoth support `--json` and `--dry-run` (preview exact commands without executing).\n\n### iterate invariant (defensive-mode delivery gate, v3.0)\n\n`iterate invariant` checks the project-level `invariants` declared in config (`invariants.ensure` file-existence assertions + `invariants.commands` exact per-module command lists). `ensure` entries must be **relative paths inside the project root** — absolute paths and `../` ancestors escaping the root are rejected outright. When no `invariants` section is configured it **degrades to `validation.commands`**, so old configs keep working unchanged. Exit 0 = invariants hold, 1 = violations found. Supports `--json` / `--dry-run`.\n\n---\n\n## How It Works\n\n### Onboarding (project knowledge base initialization)\n\nEach `/iterate` invocation checks whether `ITERATE.md` exists in the project root. If not, onboarding is triggered through either channel:\n\n- **AI Onboarding** — the AI auto-identifies the tech stack from directory structure / manifest files, producing `ITERATE.md` + `iterate.config.yaml`.\n- **CLI Onboarding** — the CLI scans then lets you confirm/adjust the tech stack and config, producing the same output.\n\nThe scan only reads file/directory **existence** and a few public context files like README.md — it does not read `.env`, keys, credentials, or other sensitive file contents. Project-specific constraints can be added with `iterate personalize`.\n\n`ITERATE.md` has two sections:\n\n- ``: AI-maintained section, updated on refresh.\n- ``: user-owned section — your hand-written conventions, forbidden areas, risk zones; preserved on refresh.\n\n### Drift detection\n\nEach `/iterate` invocation recomputes SHA-256 fingerprints of manifest files such as `package.json`, `pyproject.toml`:\n\n- No drift → silent pass\n- Drift detected → prompt: continue / incremental refresh / full re-onboarding\n\n### Personalization\n\nAn AI scan can discover the tech stack and directory structure, but not project-specific constraints. `iterate personalize` captures that knowledge:\n\n- **Forbidden areas** — files/dirs iterate must not modify → `iterate.config.yaml`\n- **Risk zones** — changes needing architecture approval → `iterate.config.yaml`\n- **Known intent** — suppresses false positives → `iterate.config.yaml`\n- **Dimension customization** — append focus to specific dimensions → `iterate.config.yaml`\n- **Fix priority order** — per-dimension fix priority → `iterate.config.yaml`\n- **Forbidden fix methods** — techniques that must not be used → `iterate.config.yaml`\n- **Project conventions & notes** — lessons learned, known pitfalls → `ITERATE.md` user area\n- **Extra validation commands** — project-specific validation commands → `iterate.config.yaml`\n\nSee [`config/iterate.config.yaml`](./config/iterate.config.yaml) for a complete example.\n\n### Scope dimension sets & review routing\n\nThe top-level `dimensions` is the default for **whole-project / global** review. For **scope-specific** goals, the skill's dimension planning (SKILL.md Phase 0) routes to the right dimension scheme:\n\n1. **Goal is empty or generic** (e.g. \"improve code quality\") → use the global `dimensions`. Zero friction.\n2. **Goal names a scope that hits a preset `dimension_sets` set** (e.g. \"review the frontend\" → `frontend`) → use that set's `dimensions` + `focus` override directly, after a quick confirmation.\n3. **Goal names an off-catalog scope** (no preset matches) → the AI **redefines dimensions from scratch**: it starts from the 9 canonical dimensions (not from global `dimensions` or any existing set, which would just be a lazy copy), picks the ones truly relevant to that scope, gives each **a scope-specific independent reason**, and may add temporary non-standard dimensions. This redefinition is recorded in `.iterate_decisions.md` under a dedicated `### Scope Dimension Redefinition (on-the-fly)` section, and is **validated by `scripts/validate.py decisions`** to ensure each reason isn't just a copy of the dimension's default focus prompt.\n\nPreset sets live only in `iterate.config.yaml` (`dimension_sets`); `ITERATE.md` renders a one-time \"Recommended Review Blueprints\" listing. Ad-hoc redefinitions are bounded to `.iterate_decisions.md` per-round — they never balloon `ITERATE.md` or `iterate.config.yaml`, so the knowledge base stays small no matter how many iterations accumulate.\n\n### Decision log (`.iterate_decisions.md`)\n\nEvery round's AI decisions — atomic fixes (direct), architectural fixes (approved + executed / deferred), reverted fixes, important AI decisions, validation results, and any off-catalog scope redefinitions — are recorded in `.iterate_decisions.md` (see the template in `templates/iterate-decisions.template.md`). This keeps the process auditable while keeping `ITERATE.md`'s AI-maintained section to a **single latest snapshot**.\n\n### Core flow\n\n```text\nStep 0 — Onboarding Check\n └─ locate project root → check ITERATE.md → drift detection → (onboarding if missing)\n\nSetup\n └─ extract goal → load config → read project context → create isolated branch/worktree\n\nLoop (round = 1 .. max_rounds)\n ├─ Phase 1: N-dimension parallel review\n ├─ Phase 2: atomic issues auto-fixed\n ├─ Phase 3: architecture issues executed after user approval\n ├─ Phase 4: record round result\n └─ Phase 5: verify → merge (if auto_merge=true) → push (if push_per_round=true)\n\nSummary\n```\n\nFor the detailed flow, see [`SKILL.md`](./SKILL.md).\n\n---\n\n## Configuration\n\nThe default config lives in [`config/iterate.config.yaml`](./config/iterate.config.yaml). Project-level config recursively overrides same-name fields in the Master config.\n\nCommon config options (each entry: key — type, default, meaning):\n\n- `goal` — string, default `\"Improve code quality\"` — iteration goal\n- `max_rounds` — int, default `7` — max rounds (cap 50)\n- `language` — string, default `\"en\"` — output language: `zh` / `en`\n- `mode` — string, default `\"iterate\"` — default execution mode: `iterate` / `defensive` (v3.0)\n- `reasoning_effort` — string?, default `null` — `low` / `medium` / `high`; `null` = follow provider default\n- `dimensions` — list, default all 9 — enabled review dimensions (whole-project default)\n- `dimension_sets` — object — named scope blueprints (`frontend`/`api`/`security`/…) with `dimensions` + optional `focus`\n- `invariants` — object — `ensure` file-existence assertions + `commands` exact per-module lists (defensive-mode delivery gate)\n- `review.scope` — string, default `\"full\"` — `full` / `changed-only`\n- `atomic.max_lines` — int, default `20` — max lines for an atomic issue\n- `atomic.max_adjacent_methods` — int, default `3` — max adjacent methods for an atomic issue\n- `git.target_branch` — string, default `main` — merge target branch\n- `git.use_worktree` — bool, default `false` — prefer a worktree for isolation\n- `git.push_per_round` — bool, default `false` — push after each round passes\n- `git.auto_merge` — bool, default `false` — auto-merge after verification\n- `validation.command_whitelist` — list, default common prefixes — allowed command prefixes (config-time safety)\n- `validation.commands` — object, default example — per-language validation commands (runtime's single authority whitelist)\n- `reviewer.evidence_validation` — bool, default `true` — hard gate: every finding's file/line must exist on disk\n- `reviewer.coverage_validation` — bool, default `true` — emit `COVERAGE_GAP` when a reviewer skipped assigned files\n- `reviewer.scope_chunk_size` — int, default `25` — files per reviewer batch in a `full` scope review\n- `onboarding.drift_check` — bool, default `true` — whether to check manifest drift\n\nExample:\n\n```yaml\ngoal: \"improve code quality, ensure all functions are ≤80 lines and tests pass\"\nmax_rounds: 7\nlanguage: en\nmode: iterate # or defensive\n\ndimensions:\n - correctness\n - security\n - performance\n - architecture\n - style-tests\n - tech-debt\n - spec-compliance\n - frontend-backend\n - ui-ux\n\n# Named scope blueprints: a scoped goal routes to its matching set instead\n# of the global `dimensions`.\ndimension_sets:\n frontend:\n dimensions:\n - ui-ux\n - frontend-backend\n - correctness\n - performance\n focus:\n ui-ux: \"responsive layout, a11y, and state handling specific to views\"\n security:\n dimensions:\n - security\n - correctness\n focus:\n security: \"OWASP Top 10, authn/authz, injection, secret handling\"\n\n# Defensive-mode delivery gate: artifacts that must exist and commands that\n# must pass at delivery (absent -> degrades to validation.commands).\ninvariants:\n ensure:\n - \"README.md\"\n commands:\n python:\n - \"pytest tests/ -x -q --timeout=60\"\n\nvalidation:\n command_whitelist:\n - \"ruff\"\n - \"mypy\"\n - \"pytest\"\n - \"swift\"\n - \"npm run\"\n commands:\n python:\n - \"ruff check src/\"\n - \"mypy src/ --ignore-missing-imports\"\n - \"pytest tests/ -x -q --timeout=60\"\n swift:\n - \"swift build -c debug\"\n typescript:\n - \"npm run compile\"\n```\n\n> Commands in `validation.commands` **must** start with a prefix in `command_whitelist`, or they are rejected.\n\n---\n\n## FAQ\n\n### Installation\n\n**Q: The installer needs GitHub access; what if my network can't reach GitHub?**\nA: The installer downloads and verifies from GitHub Release, so it needs GitHub access. If your network is restricted, use GitHub-independent alternatives:\n- Manually copy [`SKILL.md`](./SKILL.md) to the assistant directory (see \"Method B\").\n- CN mirror channels (ModelScope / SkillHub CN) are published and can provide the skill files.\n- Download from a community mirror, then run `python scripts/install.py install` locally.\n\n**Q: `npx iterate-skill-installer` reports a Python or Node version mismatch?**\nA: The installer requires Node.js 18+ and Python 3.10+. Upgrade your system Python/Node, or make sure `python3` / `node` are on the PATH. The installer prefers `python3`, then falls back to `python`.\n\n**Q: The installer puts the `iterate` CLI on my machine; can I avoid that?**\nA: Yes. `npx iterate-skill-installer` also installs the `iterate` CLI (prefer `pipx`, else `pip install --user`) to run `iterate onboard`, etc. If you don't want automatic CLI install, use the \"manually copy SKILL.md\" or \"source scripts\" methods — copy skill files only.\n\n**Q: I want to cancel mid-install; will it leave half-finished artifacts?**\nA: No. The installer does download/verify/unpack in a temp dir and only writes into the assistant dir after the target is selected. Cancelling or failing won't overwrite an already-installed skill. If one exists, reinstall prompts to overwrite by default (needs `--force`).\n\n### Usage\n\n**Q: What is this Skill for, and what isn't it for?**\nA: It's for **multi-round** code review and auto-fixing — e.g. paying down tech debt, eliminating lint/type/test issues over rounds, project-level refactoring. It's **not** for single simple changes (one line, add a comment) — use a normal conversation for those, no need for `/iterate`.\n\n**Q: `iterate` mode vs `defensive` mode — which should I use?**\nA: `/iterate` is for **reviewing/fixing existing code** until it converges. `/iterate defensive` is for when you want the AI to do **normal coding work** (add a feature, fix a bug, refactor, wire up an API, write tests): the host AI runs `guard pre-check` before editing, `guard post-check` after every change, and finishes with `invariant` plus the full review→fix→converge loop as a delivery gate. Want the AI to \"build something correctly\" → `defensive`; want it to \"polish/review what's there to zero findings\" → `iterate`.\n\n**Q: Why does the first use appear to do nothing?**\nA: Before your first `/iterate` or `iterate onboard`, the project has no `ITERATE.md` or `iterate.config.yaml`. On first use the skill does **onboarding first**: it tells you \"this is the first use, initializing the project\", scans the codebase to generate `ITERATE.md` and config, then iterates. If you see an init message instead of immediate review, that's normal. You can also run `iterate onboard` in the project root to init manually.\n\n**Q: It feels stuck on a large project, no progress?**\nA: The first round reviews multiple dimensions in parallel and can take a while. To reduce the \"stuck\" feeling, the skill now streams progress: `▶ Round N/max` at round start, per-dimension `⏳ reviewing …` during parallel review, and `✅ Round N complete` at round end. To speed it up:\n- Set `review.scope` to `changed-only` in `iterate.config.yaml` to review only this round's changes.\n- Split reviewer tasks by directory/module (see the Reviewer Prompt checklist in SKILL.md).\n- Lower `max_rounds` to avoid unnecessary extra rounds.\n\n**Q: What does the drift prompt mean at runtime?**\nA: Drift detection compares SHA-256 fingerprints of manifest files like `package.json`, `pyproject.toml` (onboarding-time fingerprints vs the current project state). If deps or config changed, it means the project state differs from the last onboarding; you'll be prompted to: continue / incremental refresh (`iterate refresh`) / full re-onboarding (`iterate reonboard`). To check drift without triggering a run, use `iterate fingerprint` (exits 1 when drift is detected).\n\n**Q: My changes weren't merged to main or pushed remotely?**\nA: That's the **secure default**: `git.auto_merge` and `git.push_per_round` both default to `false`, so changes stay on an isolated `iterate/*` branch or worktree for you to review before deciding to merge/push. To auto-merge/push, enable those two options explicitly in `iterate.config.yaml`.\n\n**Q: I edited `iterate.config.yaml` manually but some validation commands don't work?**\nA: Commands in `validation.commands` **must** start with a prefix in `validation.command_whitelist`, or they're rejected. Extra validation commands added by personalization also only accept 30+ pre-approved tool prefixes and reject shell metacharacters like `;`, `|`, `&` — for safety, so the project config can't run arbitrary commands.\n\n**Q: I want to add a new validation tool (e.g. `sphinx`), how?**\nA: The strict whitelist only accepts pre-approved tool prefixes (so project config can't run arbitrary commands). Two **safe** ways to add a tool:\n- **Operator-level environment variable (recommended, no source change)**: set `ITERATE_EXTRA_SAFE_COMMAND_PREFIXES=sphinx` in the runtime environment (comma/space-separated for multiple tools). This variable **can only be set at the system level**, not in the project config, so it doesn't break the security model; entries containing `;`, `|`, `&` are dropped (fail-closed).\n- **Source-level extension**: append the tool name to `KNOWN_SAFE_COMMAND_PREFIXES` in `iterate_cli/personalize.py`, then reinstall.\n- Or configure directly via `validation.command_whitelist` + `validation.commands` (must pass `python scripts/validate.py config`).\n\n### Security\n\n**Q: Does this Skill read my keys / `.env`?**\nA: No. The skill and onboarding scan only read manifest existence and public context files like `README.md` / `CLAUDE.md`; it explicitly does not read `.env`, `*.key`, `secrets/`, `*.pem`, etc. `projectContext` also never contains API keys, passwords, or tokens.\n\n**Q: Is updating safe?**\nA: Yes. `scripts/install.py update` and `npx iterate-skill-installer` download the pre-uploaded `iterate-skill.tar.gz` + `SHA256SUMS.txt` from the GitHub Release and force SHA256 verification after download; install is rejected if missing or mismatched.\n\n---\n\n## Security\n\n- **High autonomy**: this skill autonomously edits files, runs `git` operations, and runs commands in `validation.commands`. All changes first happen on an isolated branch/worktree; architecture fixes require user approval.\n- **Secure-by-default Git**: `push_per_round` and `auto_merge` both default to `false`; merge/push are opt-in, so changes stay on the iteration branch unless explicitly enabled. Rollback uses non-destructive commands like `git restore`.\n- **Two-layer command whitelist**:\n - Command prefixes are validated at config time.\n - Personalization `extra_validation_commands` only accept 30+ pre-approved tool prefixes and reject shell metacharacters like `;`, `|`, `&`; commands are re-validated on load/merge, so hand-edited config can't bypass the whitelist.\n- **Sensitive files**: this skill and its installer never read `.env`, keys, credentials, etc.; onboarding scans only check the existence of public files like manifests.\n- **Update security**: `scripts/install.py update` and `npx iterate-skill-installer` download the pre-uploaded `iterate-skill.tar.gz` + `SHA256SUMS.txt` from the GitHub Release and force SHA256 verification; rejected if missing or mismatched.\n- **Installer disclosure**: `npx iterate-skill-installer` also installs the `iterate` CLI to PATH (prefer `pipx` isolated, else `--user`). If you don't want the CLI, use the manual-copy or source-script method.\n\n---\n\n## Directory Structure\n\n```text\niterate-skill/\n├── SKILL.md # core skill file\n├── README.md # this file (English)\n├── README.zh-CN.md # Chinese README\n├── LICENSE # MIT license\n├── CONTRIBUTING.md # contribution guide\n├── CHANGELOG.md # version changelog\n├── pyproject.toml # iterate CLI package definition\n├── npm-installer/ # npx one-command installer source\n│ ├── bin/cli.js\n│ ├── lib/installer.js\n│ └── package.json\n├── config/\n│ ├── iterate.config.yaml # default config (Master)\n│ ├── config.schema.json # config JSON Schema\n│ ├── dimensions.yaml # aggregated dimension definitions\n│ └── dimensions/ # data-driven dimension definitions\n├── examples/ # per-language project examples\n├── harness/ # two engineering components of the iterate ecosystem (monorepo)\n│ ├── iterate-harness/ # standalone headless engine (npm: iterate-harness, command ih)\n│ │ ├── src/iterate_harness/ # CLI / engine / web / UI source\n│ │ ├── frontend/ # terminal / web frontend UI\n│ │ ├── npm/ # npm wrapper (ih)\n│ │ └── scripts/ # install scripts and e2e tests\n│ └── iterate-plugin/ # dsh desktop plugin (npm: iterate-plugin)\n│ ├── src/ # server logic (TypeScript, compiled to dist/)\n│ ├── lib/ # client UI injection entry\n│ └── cordis.patch.yml # dsh bundle declaration\n├── templates/\n│ ├── ITERATE.template.md # knowledge-base template\n│ └── iterate-decisions.template.md # per-round decision log template\n├── iterate_cli/ # onboarding CLI source\n│ ├── cli.py # top-level command dispatcher\n│ ├── guard.py # guard pre/post-check (defensive mode)\n│ ├── configcmd.py # iterate config get/set\n│ ├── dimension_sets.py # scope dimension-set suggestion / normalize / merge\n│ ├── wizard.py / scan.py / generator.py / refresh.py / personalize.py /\n│ │ doctor.py / show.py / fingerprint.py / tui.py\n│ └── data/\n│ ├── ITERATE.template.md # wheel-packaged template\n│ └── config.schema.json # wheel-packaged schema (kept in sync)\n├── scripts/\n│ ├── install.py # install/uninstall/config/validate script\n│ ├── validate.py # config & decision-log validation (incl. scope redefinition checks)\n│ └── requirements.txt # script dependencies\n├── tools/ # per-assistant implementation examples\n├── tests/ # unit tests\n└── .github/workflows/ # CI / Release\n```\n\n---\n\n## Contributing\n\nIssues and PRs are welcome!\n\n1. Fork this repo\n2. Create a feature branch: `git checkout -b feat/your-feature`\n3. Commit: `git commit -m \"feat: description\"`\n4. Push: `git push origin feat/your-feature`\n5. Open a Pull Request\n\nPlease keep `SKILL.md` in its bilingual (English/Chinese) structure and add config examples for new features.\n\n---\n\n## Disclaimer\n\nThis project is provided \"AS IS\", without warranty of any kind, express or implied, including but not limited to warranties of merchantability, fitness for a particular purpose, and non-infringement.\n\n**Automated code review and fixing carry inherent risks.** Changes made in normal mode are generated by AI models and may introduce defects, regressions, or unexpected behavior. Before merging changes, you should:\n\n- Review every diff individually before applying to `main` or pushing.\n- Ensure the project is under git version control and can be rolled back (`git restore`, revert, or restore from backup).\n- Run your project's own tests and build checks after each round of fixes.\n- Never run this project on keys, credentials, `.env`, or any files you're not allowed to modify; configure the corresponding protected paths in `iterate.config.yaml`'s `protected_paths`.\n\nYou are solely responsible for the code you produce, modify, or commit while using this project. By using this project you agree that the maintainers and contributors are not liable for any loss, damage, or legal consequences arising from your use of it.\n\n---\n\n## License\n\n[MIT](./LICENSE) © 2026 iterate-skill contributors\n\nFile v3.4.4:_meta.json\n\n{\n \"ownerId\": \"kn72jg53khrabazt1xdtaqs8ah8awde5\",\n \"slug\": \"iterate-skill\",\n \"version\": \"3.4.4\",\n \"publishedAt\": 1791079858627\n}\n\nFile v3.4.4:scripts/requirements.txt\n\n# iterate-skill 校验脚本与安装脚本依赖\n# 许可证：MIT / Apache-2.0 / BSD 等宽松许可\njsonschema==4.26.0\nPyYAML==6.0.2\nrich==13.7.1\n\nFile v3.4.4:CHANGELOG.md\n\n# Changelog\n\n本项目遵循 [Semantic Versioning](https://semver.org/)。\n每个版本变更记录在下方，最新版本在最前。\n\n---\n\n## [3.4.4] — 2026-09-30\n\n本轮为无人值守的全量复检（Bugbot 式代码评审 + UX/功能缺口评审），共 24 个提交，\n全部为修复与文档变更，无新增功能（因此为 patch 版本）。\n\n### 修复 / Fixes — 安装与发布链路\n\n- **安装器版本解析（阻断级）**：三处安装器均调用 `/releases/latest`，该端点返回\n 「最新发布」而非「最新携带安装包的发布」——线上实测指向 `v2.1.5`（仅有\n `SHA256SUMS.txt`），导致**安装 100% 失败**、`iterate update` 永远报告\"已是最新\"。\n `updater.RELEASES_API_URL` 与 `scripts/install.py` 改查 `/releases?per_page=100`\n 并挑选第一个真正携带 `iterate-skill.tar.gz` 的发布（`_select_skill_release`），\n 离线发布（draft/prerelease）与版本回退均有独立报错文案。实测：旧逻辑取\n `v2.1.5`，新逻辑取 `v3.4.2`。\n- **命令注入：拒绝包管理器远程执行动词**：`personalize` 的安全命令白名单\n （`KNOWN_SAFE_COMMAND_PREFIXES`）按**前缀**匹配，`npx` 在列意味着\n `npx -y evil` 只要出现在配置里就会以 `shell=True` 执行任意代码。已将 `npx`\n 移出白名单，并新增 `_REMOTE_EXEC_VERBS` 闸门拦截 `npm exec`/`npm x`、\n `pnpm dlx`/`pnpm exec`、`yarn dlx`、`bun x`/`bun exec`；`npm run build`、\n `npm test` 等本地脚本仍然放行。\n- **tar 解压拒绝 Windows 盘符成员**：`C:/evil` 这类成员在 POSIX 下既非绝对路径、\n 也不含 `..`，两道既有防线全部漏过。新增 `_DRIVE_LETTER_RE` 于解压前拦截。\n- **npm 安装器传输后大小校验**：`TARBALL_MAX_BYTES` 此前只在 curl 阶段生效，\n 新增 `enforceDownloadedSize()` 在传输完成后按落盘体积复核，超限即删除并失败。\n- **Qoder 包排除 `kernel/` 等目录**：`publish_qoder.MANDATORY_EXCLUDES` 对齐\n `release.yml` 的路径排除（`harness`/`kernel`/`tests`/`.githooks`/`badges`），\n 此前这些目录会混入发布产物。\n- **`validate` 非 UTF-8 配置就地报告**：`load_schema`/配置读取改抛 `ValueError`\n 并输出可读错误，不再抛原始 `UnicodeDecodeError` traceback。\n\n### 修复 / Fixes — CLI 输出契约（`--json` 与退出码）\n\n- **`--json` 的 stdout 恒为单个可解析文档**：\n - `refresh --json` 先向 **stdout** 打印人类警告再打印 JSON，令\n `iterate refresh --json | jq` 直接解析失败；警告仅在非 `--json` 路径输出。\n - `config --json`、`config get KEY --json` 在配置缺失/键名未知时输出**空**\n stdout，而同一函数的\"中间节不是映射\"分支却输出 `{\"error\": ...}`——一个命令\n 两套契约；现已统一为 `{\"error\": ...}`。\n - 任意子命令 `-p /nonexistent` 同样只给退出码不给 JSON，已补上。\n- **`doctor --json` 的 `healthy` 与退出码一致**：此前 `healthy` 只看\n `has_errors()`，而退出码用 `errors or (strict and warnings)`，于是\n `doctor --strict` 下\"仅告警\"报告打印 `\"healthy\": true` 却退出 1，\n `jq .healthy` 与 `$?` 对同一次运行给出相反结论。现 `healthy` 定义为\n `exit code == 0`，并同时输出 `blocking`/`strict`/`has_errors`/`has_warnings`，\n 不丢信息；未加 `--strict` 时取值不变。\n- **`show` 与 `status` 对损坏配置给出同一结论**：两者的渲染条件完全相同，\n 但 `show` 无条件返回 0、`status` 返回 1（其注释写明理由：否则 CI 会把坏配置\n 当成功）。挂 `show` 的流水线因此一直是绿的。现 `show` 亦退出 1，TUI 路径\n 并给出处置建议。\n- **`config set` 用法错误退出 2**：裸 `iterate`、交互命令带 `--json`、\n `update --json` 缺 `--yes` 均返回 2（\"你调用错了\"），而\n `config set KEY` 缺 `VALUE` 返回 1（\"操作失败\"），自动化无法区分。\n 现统一为 2；**操作性**失败（如 `max_rounds 999`）仍为 1，测试已钉住两侧。\n- **ASCII 横幅不再污染重定向输出**：横幅是 8 行块状字符，此前在任何 isatty\n 检查之前写入 stdout，于是 `v=$(iterate --version)` 捕获到 8 行艺术字加版本号，\n 与调用点自己写的\"非 TTY stdout 只输出一行裸 `iterate `\"直接矛盾，\n 也破坏了 SKILL.md 推荐的 `iterate config get KEY` 捕获用法。横幅现仅在交互\n 终端显示。\n- **`--json` 帮助文本补全命令清单**：`iterate --help` 只列了\n `status/show/doctor/refresh/config`，但 `guard`、`invariant`、`fingerprint`、\n `update`（以及 `--version`）同样支持，脚本作者会误以为不支持。现全部列出，\n 并写明\"除交互命令外，失败路径也保证 stdout 只有一个 JSON 文档\"。\n\n### 修复 / Fixes — 非交互（CI/管道）场景下的提示\n\n- **`personalize --clear` 不再对管道抛 EOF**：此前无护栏地调用 `input()`，\n 管道 stdin 触发 EOF 后落入通用处理器，提示\"输入已结束（Ctrl+D / EOF）\"却不提\n `--yes`——而 `--yes` 正是为此存在的。现与 `iterate update` 一致：先检测\n 非交互 stdin 并提示 `Pass --yes to confirm ...`，再画提示符。\n- **`install.py` 非交互提示点明处置**：`update` 缺 `--yes` 时只报\n \"Update cancelled.\"，`install` 缺 `--ai` 时只报\"No assistants selected.\n Installation cancelled.\"，均未说明是 stdin 导致、也未点出 `--yes` /\n `--ai ` / `--ai all`。现两类均先给出诊断再给标志位。\n- **`guard pre-check --dry-run` 不再假装预览**：`pre-check` 是静态校验、从不\n 执行命令，却打印 \"guard-pre: DRY-RUN preview (nothing executed)\"，暗示常规路径\n 会执行、且该标志改变了结果；其帮助文本也承诺\"预览将要执行的确切命令\"，\n 是 `pre-check` 无法兑现的承诺。现改为如实说明（\"guard-pre is read-only ...\"），\n 并把帮助文案的作用域限定到 `post-check`。JSON 负载中的 `dry_run` 字段保持不变。\n\n### 修复 / Fixes — 正确性\n\n- **`config --json` 序列化日期类型**：date/datetime 值直接 `json.dumps` 抛\n `TypeError`，三处输出点补 `default=str`。\n- **`iterate update --check --assistants` 每条路径都校验**：此前 `--check` 分支\n 与交互\"先检查后确认\"分支跳过校验，拼错的名字（如 `cluade`）静默退出 0；\n 错误信息现在直接列出 `updater.ASSISTANT_SKILL_DIRS` 而非指向 `--help`。\n- **`generate_refreshed_md` 末尾标记用 `rfind`**：用户自有的结束标记若在文件中\n 出现多次，`find` 命中第一处导致标记重复、其后内容被吞。\n- **`doctor --fix` 重复计数与备份命名**：重复数此前把整条字符串条目也算进\n 差值（报出比实际多的数字）；备份名改为 `文件名-时间戳-随机 6 位十六进制`，\n 同一秒内的多次修复不再互相覆盖。\n- **`guard` 超时杀进程路径不再抛异常**：`proc.kill()` 在进程已退出时抛\n `ProcessLookupError`（`OSError` 子类），会以 traceback 掩盖真正的超时结论；\n 现 `killpg` 与 `proc.kill` 分别兜底。\n- **`prompt_int_in_range` 越界默认值改为夹取**：`default` 超出 `[min, max]` 时\n 既不接受也不拒绝，陷入无限循环（回退该修复会让测试套件挂死）。\n- **`uninstall` 目标去重与逐项容错**：`claude`/`claude-code` 同指向\n `.claude/skills/iterate`（`gemini`/`gemini-cli` 同理），`--ai all` 时第一个别名\n 删完、第二个别名撞上\"无 SKILL.md 标记\"的防御复检，于是一次**完全成功**的卸载\n 却打印 \"Skipped 2 target(s) that did not look like iterate-skill installations.\"。\n 现按目标目录去重；`shutil.rmtree` 亦加护栏，单个只读/锁死目录不再以原始\n traceback 中断其余目标，部分失败退出码为 1。\n- **安装摘要框按显示列而非字符数填充**：`_frame_box` 用 `len()` 计算填充，CJK\n 字形占两列却只算一列，右边框 `│` 溢出、上下横线差一列。新增本地\n `_display_width`（与 `iterate_cli.tui` 同算法，因该脚本必须在安装前独立运行\n 而无法依赖 `iterate_cli`）。\n- **下载量徽章脚本容忍 HTTP 帧错误**：`http.client.HTTPException`\n （`IncompleteRead`/`BadStatusLine`/`LineTooLong`）既非 `OSError` 也非\n `ValueError`，截断响应会以 traceback 打断整个更新，恰好放弃了\"复用上次已提交\n 数值\"这条为该场景而写的回退路径。现已一并捕获，`fetch_json` 文档亦声明该类型。\n\n### 重构 / Refactor\n\n- `generator._guess_dir_purpose` 移除从未被读取的 `scan` 形参，唯一调用方一并更新。\n\n### 测试 / Tests\n\n- 新增 `tests/test_command_safety.py`（9 例：远程执行动词拦截、`npx` 移除、\n 本地 `npm run`/`test` 仍放行）。\n- `tests/test_updater.py` 发布夹具改为 JSON **列表**以匹配新端点，并补 6 例发布\n 选择 + 4 例盘符路径。\n- `tests/test_install_script.py` 新增：卸载别名去重与逐项容错（4）、摘要框对齐\n （5）与显示宽度（6）、越界默认值夹取（4，回退修复会挂死）、非交互提示点明\n 标志位（2）、非 UTF-8 输入（6）。\n- `tests/test_onboarding.py` 新增：`--version` 重定向输出为单行裸值（2）、\n `--json` stdout 单文档契约（4）、`show`/`status` 损坏配置一致（4）、\n `personalize --clear` 非交互拒绝与 `--yes` 穿透（2）。\n- `tests/test_config.py` 新增：`--json` 错误对象契约（3）与用法/操作退出码分工（2）。\n- `tests/test_doctor.py` 新增 `TestStrictJsonConsistency`（4）；\n `tests/test_guard.py` 新增 dry-run 语义（3）；`tests/test_tui.py` 新增\n `TestJsonHelpText`（3）与横幅 TTY 闸门（2）；`tests/test_update_downloads_badge.py`\n 新增 HTTP 帧错误回退（1）。\n- 全量 `pytest tests/ -q` 1236 通过；`ruff check .` 通过；\n `npm test --prefix npm-installer` 通过；24 个提交逐一通过 ruff 与\n 全量 `.py` 语法校验，且均不含 `harness/`、`kernel/` 路径。\n\n---\n\n## [3.4.3] — 2026-09-19\n\n### 修复 / Fixes\n\n- **Guard 命令输出有界与超时收敛（F26-F31）**：`guard._run_command` 改为 `Popen` +\n 分块 drain（`_DRAIN_CHUNK_CHARS=64 KiB` 逐块读、超长行/超宽字节被截断，`_OUTPUT_LINE_CAP=200`/\n `_OUTPUT_BYTE_CAP=1 MiB`）+ `_COMMAND_TIMEOUT_SECONDS=600` 超时经 `start_new_session`\n 进程组 `SIGKILL`（连子进程一起杀），杜绝命令刷屏耗尽内存或永不返回。\n- **`iterate --json --version` 严格机读**：纯 JSON 单行输出（无 banner、exit 0），供脚本判读。\n- **所有权标记缺失/损坏**：`personalize` 告警而非静默跳过（非 UTF-8 读取不崩溃）。\n- **忽略匹配**：`_matches_ignore` 用 `fnmatchcase` 全平台大小写敏感；`_safe_extractall`\n Python<3.12 回退路径拒绝 symlink/hardlink/绝对路径成员。\n- **安装器 fail-closed（ReleaseIntegrityError）**：校验和缺失/下载失败/校验不匹配一律\n exit 1、不落文件、绝不打印 \"Update complete.\"；纯网络失败才回退本地源；`_parse_checksum`\n 非 UTF-8 不崩溃。npm 安装器 null 退出码归一 1、`runCommand` 10 分钟超时 + 1 MiB 尾部缓冲；\n `_argmax`/`_is_async_command`/`_output_mode_validate` 均拒绝非法值。\n- **配置写入原子性**：`set_config_values` 校验失败回滚并恢复原始字节、无 `.tmp` 残留；\n `interactive_config` 遇损坏现有 config 拒绝（返回 1）且文件原样；`install_command`\n 多助手部分失败逐个报告（exit 1）；`publish_qoder._copy_tracked_tree` 仅拷贝已跟踪文件，\n 特批 untracked/scratch/dev/harness 一律不进入产物。\n\n### 测试 / Tests\n\n- 新增回归覆盖：`tests/test_guard.py`（分块 drain、超时杀进程、非 UTF-8 报错不崩溃）、\n `tests/test_install_script.py`（EOF/非 UTF-8/校验和 fail-closed/绝对路径/符号链接拒绝）、\n `tests/test_validate.py`（`validate_dimensions` 非 UTF-8 不崩溃）、\n `tests/test_publish_qoder.py`（`_copy_tracked_tree` 只含已跟踪文件）、\n `tests/test_onboarding.py`（corrupt config `status --json` 返回 1、upsert 原子性）。\n\n---\n\n## [3.4.2] — 2026-09-18\n\n### 修复 / Fixes\n\n- **守卫命令防挂死与内存有界（F7）**：`guard._run_command` 原先用 `subprocess.run` 无上限收集输出，命令一直刷屏会耗尽内存、无 `timeout` 时永不返回；现改为 `Popen` + 有界尾部缓冲（`_OUTPUT_LINE_CAP=200` 行 / `_OUTPUT_BYTE_CAP=1 MiB`）+ `_COMMAND_TIMEOUT_SECONDS=600` 超时 + `start_new_session`（`_kill_process_tree` 用进程组 `SIGKILL` 连子进程一起杀）。\n- **`--json --version` 输出机器可读（F5）**：`iterate --json --version` 先前输出的是人类文案 `Iterate v3.4.1` + banner 引导，JSON 消费者无法解析版本；现严格输出 `{\"command\":\"version\",\"version\":\"...\"}` 且不打印 banner，退出码 0。\n- **迭代文件中所有权标记失效时告警（F4）**：`personalize.build_updated_iterate_md` 在 ITERATE.md 缺少/损坏 `` 标记时静默返回 None，用户数据被悄悄跳过；现发 `tui.warning`（\"ownership markers ... user-owned section cannot be updated\"）后交给主流程处理。\n- **忽略规则大小写确定性（F6）**：`fingerprint._matches_ignore` 用 `fnmatch.fnmatch`（macOS/Windows 上大小写不敏感）、Linux 敏感，行为随平台漂移；改 `fnmatchcase` 全平台大小写敏感。\n- **Python<3.12 解压回退路径拒绝软/硬链接（F3）**：`updater._safe_extractall` 在无 `tarfile.data_filter`（<3.12）的回退分支上裸 `extractall`，软/硬链接成员可借链接链逃逸；现该分支对任何 symlink/hardlink 成员一律 `TarError` 拒绝（发布 tar 包本不含链接）。\n- **更新完整性失败必拒（F8）**：`install.update_command` 在缺 `checksum_url` / 校验和下载失败 / 条目缺失 / SHA-256 不匹配时曾回退\"本地目录更新的成功路径\"（exit 0、\"Update complete.\"），实际装的却是未经验证的旧代码；新增 `ReleaseIntegrityError`，完整性失败一律失败快返 exit 1、不装任何文件，\"网络下载失败\"（纯网络错误）仍合法回退本地源（exit 0）。\n- **校验和解析防崩溃（F11）**：`install._parse_checksum` 对非 UTF-8 文件体 decode 直接抛 `UnicodeDecodeError` 崩溃；改捕获后返回 None，由调用方按完整性失败处理。\n- **安装部分失败不中断（F12）**：`install.install_command` 对多助手安装时某个助手拷贝失败会整体崩溃/静默；现逐个助手 try/except，失败者记录并继续，最终以 `Exit code 1` + \"Installation incomplete\" 明确报告部分成功。\n- **npm 安装器退出码与超时硬化（F9/F10）**：`npx` 子进程被信号杀死时 `close` code 为 null，被当作成功；`bin/cli.js` 与 `runPythonInstall` 统一把非数字/null 归为 1。`runCommand` 原无超时上限、输出无界收集：新增 `DEFAULT_COMMAND_TIMEOUT_MS=10min`（超时 `SIGKILL`，报错含时长）与 `TailBuffer` 1 MiB 有界尾部缓冲。\n\n### 测试 / Tests\n\n- 全量 1124 个 Python 测试通过、`ruff check` 通过、`npm test` 通过。新增 16 项：守卫有界输出（`seq 5000` 尾部保留且 < 1 KiB）与超时杀进程（monkeypatch 1s / `sleep 30`）；`--json --version` 结构断言；标记损坏告警文案；`fnmatchcase` 大小写敏感；<3.12 分支拒绝软链接、良性树放行；完整性失败 4 例（缺 URL / 校验和下载失败 / 条目缺失 / SHA 不匹配）均 fail-closed、纯网络失败回退本地 exit 0、`update` 完整性失败 exit 1 且不装文件、校验和\"Update complete.\"不可达；非 UTF-8 校验和返回 None；多助手部分失败 exit 1 且报告；npm 端超时拒绝、1 MiB 尾部有界、null 退出码归一为 1。\n\n---\n\n## [3.4.1] — 2026-09-16\n\n### 修复 / Fixes\n\n- **`iterate update` 子进程超时生效（F28）**：`updater._run_command` 先前只把 `timeout` 参数接住却从未传给 `subprocess.run` —— `GIT_TIMEOUT_SECONDS`（120s）与 `PIP_TIMEOUT_SECONDS`（600s）是花瓶常量，`git pull --ff-only` / `pip install` 一旦挂起，整个 `iterate update` 会无限阻塞；现生产默认 runner 真正以 `timeout=` 传给 `subprocess.run`，`subprocess.TimeoutExpired` 转成可读的 `RuntimeError`（清晰报错指令与超时时长），注入的测试 runner 保持原 `(argv)` 契约不变。\n- **安全解压覆盖目录成员与符号链接（F29）**：`updater._safe_extractall` 此前只对非目录成员做路径穿越检查，`../escape/` 这类目录成员在无 `tarfile.data_filter` 的 Python（<3.12）回退路径上可逃逸；现每个成员（含目录）统一校验为相对路径、拒绝绝对路径/`..` 段，符号链接/硬链接成员的链接目标也拒绝绝对路径与逃逸目标，设备/管道成员照旧拒绝。\n- **下载上限按字节精确执行（F30）**：`updater._urlopen_bounded` 原按\"块数\"近似封顶（最多可读到 ~52.4 MiB > 50 MiB），现改为累计真实字节数，超过 `MAX_DOWNLOAD_BYTES` 立即中断。\n\n### 加固 / Hardening\n\n- **`iterate update --assistants` 白名单（F31）**：`--assistants` 传入未知助手名（如 `--assistants cluade`）此前被静默忽略，只更新了命中的助手子集，极易误判为\"全部未装\"；`run_update` 现在**在任何网络请求前**用 `ASSISTANT_SKILL_DIRS` 校验名称，未知名字失败快返（`outcome.assistants_unknown`，CLI 列出合法名 + 退出码 1，`--json` 含 `assistants_unknown` 字段）。`--assistants` 空列表（= 跳过技能目录刷新）与缺省（= 全部）不受影响。\n\n### 测试 / Tests\n\n- 全量 1104 个 Python 测试通过、`ruff check` 通过。新增 15 项：生产 runner 超时确实传给 `subprocess.run`、注入 runner 契约不变、`TimeoutExpired` 转可读错误；目录穿越 / 绝对路径 / `..` 逃逸 / 绝对链接目标 / 逃逸链接目标 各自被拒，良性树正常解压；50 MiB 上限恰好放行、多 1 字节拒绝；`--assistants` 已知名 ok / 未知名上报 / 空列表合法 / 未知名失败快返不碰网络 / `to_dict` 含 `assistants_unknown`。\n\n---\n\n## [3.4.0] — 2026-09-15\n\n### 新增 / Features\n\n- **`iterate update` 自更新命令**：一键把 CLI 与所有已安装的助手技能目录更新到最新 GitHub Release，全程不依赖 ~/.agents/skills 结构：\n - **校验先行**：从 GitHub API 拉取 latest release（`iterate-skill.tar.gz` + `SHA256SUMS.txt`），任何写入发生前先做 50 MiB 有界下载、SHA-256 逐字节核对、安全解压（拒路径穿越/解压炸弹/设备节点）；校验不通过一律拒绝写入。\n - **双目标更新**：(a) 按 `scripts/install.py` 的 `SUPPORTED_AI` 布局刷新已安装助手技能目录（SKILL.md / config/ / iterate_cli/ / scripts/ / templates/ ...，剔除 harness/ 并清理历史残留）；(b) 重装 CLI 包——pip 安装走 `--force-reinstall --no-deps` 已验证解压源码，源码安装走 `git pull --ff-only` + `pip install -e`。\n - **交互语义**：默认交互式确认（默认 No，与安装器一致）；非交互 stdin 需显式 `--yes`；`--check` 只对比版本零写入；`--json` 输出结构化结果（需 `--yes`）；`--assistants` 可限定刷新范围；单一助手失败不阻断其余更新。\n - **`iterate --version` 更新提示**：24h 缓存式一次性提示\"有新版本，运行 `iterate update`\"（`ITERATE_UPDATE_CHECK=0` 可关闭；任何异常静默降级，绝不破坏 `--version`）。\n\n### 测试 / Tests\n\n- 全量 1089 个 Python 测试通过、`ruff check` 通过。新增 47 项：`tests/test_updater.py` 覆盖版本比较、release 发现（mock 网络，含 403/404/网络异常/坏 JSON）、SHA-256 校验匹配/不匹配/缺条目、安全解压与顶层布局断言、安装方式检测、助手目录检测去重、技能目录复制/替换/清理/harness 剔除/符号链接祖先防护、pip/source 两种 CLI 重装（mock runner）、`run_update` 全流程（不可达/已是最新/未确认取消/校验失败拒绝/单助手失败容错）、缓存提示；`tests/test_updater_sync.py` 用 AST 锁定 `ASSISTANT_SKILL_DIRS`/`REQUIRED_RELEASE_PATHS`/`OPTIONAL_RELEASE_PATHS` 与 `scripts/install.py` 三份同名常量永不漂移。\n\n---\n\n## [3.3.1] — 2026-09-14\n\n### 修复 / Fixes\n\n- **doctor dimension_sets 不可哈希崩溃**：手写配置里 `dimensions` 含非字符串条目（如内嵌列表 `[[], \"correctness\"]`）时，去重检查 `d in seen` 直接抛 `TypeError: unhashable type: 'list'` 令整个 `iterate doctor` 崩溃；现先归一化为 `str` 再判定，崩溃降级为常规 unknown-dimension 警告（doctor.py `_check_dimension_sets` 去重与 `unknown` 两遍归一化逻辑统一）。\n\n### 加固 / Hardening\n\n- **config schema 拒绝空命令列表**：`validation.commands` 与 `invariants.commands` 各模块条目增加 `minItems: 1`（与 `command_whitelist` 一致）——空数组毫无意义（运行时本就自动丢弃空模块），直接在 schema 层面报出；`iterate_cli/data/config.schema.json` 打包副本同步。\n\n### 维护 / Maintenance\n\n- **npm 安装器清理**：`parseArgs` 移除重复死亡的 `token` 默认键（`normalizeToken(...)` 永远覆盖前一默认值，行为不变）；新增 `parseArgs([])` 默认 token 归一化断言。\n\n### 测试 / Tests\n\n- 全量 1041 个 Python 测试通过、`ruff check` 通过、npm 安装器测试通过；新增覆盖：不可哈希 dimension 条目不再崩溃（降级为 warn）、空命令模块触发 schema minItems 警告、加载器默认 token 归一化。\n\n---\n\n## [3.3.0] — 2026-09-12\n\n### 新增 / Features\n\n- **guard pre-check 工具可用性检查**：`guard pre-check` 对每条配置的验证命令检查其首 token 对应的可执行文件是否在 PATH 上（shell 内建如 `true` 除外）；缺失时判定 `FAIL` 并列出缺失工具，防止\"命令配置了但环境里根本没有该工具\"的假绿灯。\n- **`invariants.ensure` 路径安全**：`iterate invariant` 的 file-existence 断言只接受项目根目录内的相对路径——绝对路径与 `../` 越出项目根的逃逸一律 `FAIL`（拒绝在交付门禁里让断言指向项目外文件）。\n- **`iterate status` 区分损坏与缺失配置**：`iterate.config.yaml` 存在但无法解析时，status 退出码 1 并提示\"could not be parsed → 运行 `iterate doctor`\";缺失时保持退出码 0 并提示仅存在 ITERATE.md。`--json` 新增 `config_exists` / `config_ok` 字段供脚本区分。\n- **doctor 标量 section 硬错误**：`review:` / `git:` / `validation:` 为标量（非 mapping）时如实上报 error 而非含糊跳过。\n- **install.py / npm 安装器加固**：GitHub API 请求增加连接错误（`http.client.HTTPException`）分类提示；`_parse_checksum` 强制 64 位十六进制摘要（非 hex / 截断一律忽略，大写归一化）；`_safe_extractall` 在所有 Python 版本上拒绝 device/fifo 归档成员；`parse_value` 改为 JSON 优先、YAML 兜底；`set_nested_value` 拒绝空段；`init_config` 原子写入。npm 安装器 token 自动 trim 空白（`GITHUB_TOKEN` 常带尾随换行），并在携带 `Authorization` 的 API 请求上禁用跨主机重定向（curl 会把自定义 `-H` 头原样转发到重定向链上的每个主机）。\n- **publish_qoder.py 校验加固**：`_git_archive_extract` 显式以仓库根为 cwd 运行 `git archive`（否则从子目录调用时 pathspec `:!harness` 相对当前目录匹配，可能把 `harness/` 打包进去）；zip 顶层目录检查改为校验**每个**条目（此前只查 `names[0]`，可被排序在后的外来顶层目录绕过）；`_find_harness` 同时覆盖名为 `harness` 的文件与目录。\n\n### 修复 / Fixes\n\n- **tui 用户文本富文本转义（F24）**：tui 渲染用户输入的文本（如 `[module]`）前统一 `rich.markup.escape`，避免把用户文本误当 markup 标签。\n- **doctor C2/C3/C4/C5**：metachar 报错与无白名单校验不再打印自相矛盾的成功行；`run_doctor_fix` 改用原子写入并捕获 `OSError`/`YAMLError`；`_render_next_actions` 覆盖 `invariants.ensure` 异常的动作建议。\n- **install.py**：`_download_bytes` / `_fetch_latest_release_info` 分类网络连接错误；`set_config_values` 捕获 `set_nested_value` 的空段 ValueError 并清晰报错。\n\n### 测试 / Tests\n\n- 全量 1040 个 Python 测试通过、`ruff check` 通过、npm 安装器测试通过；新增覆盖：MissingCommandTool / shell 内建免二进制、ensure 绝对路径与项目外逃逸拒绝、status 损坏配置 TUI/JSON、doctor 标量 section / YAML 序列化错误 / next-actions、checksum 64-hex 策略、device/fifo 归档成员拒绝、init_config 原子失败不回滚脏文件、zip 外来顶层目录与嵌套 harness 文件。\n\n---\n\n### 维护 / Maintenance\n\n- 日常审查与发版：全部测试通过（1002 passed），ruff 检查通过，无新增问题。\n\n## [3.2.2] — 2026-09-09\n\n### 修复 / Fixes\n\n- **doctor 标量 onboarding 配置崩溃**：`onboarding:` 为标量字符串（手写配置常见）时，`_check_manifest_drift` 调用 `.get()` 抛出 `AttributeError`。改用 `isinstance` 守卫，与 `refresh.py`/`wizard.py` 同一模式。\n- **ruff 代码质量**：修复 `I001`（import 排序）、`BLE001`（盲捕异常）、`RUF059`（未使用解包变量）。\n\n### 测试 / Tests\n\n- 新增 `TestScalarOnboardingConfig` 回归测试，确保标量 onboarding 配置不再让 doctor 崩溃。\n\n---\n\n## [3.2.1] — 2026-09-07\n\n### 修复 / Fixes\n\n- **命令白名单运行时二次校验（防绕过）**：`iterate guard` 运行时执行校验命令前，除了外壳元字符检查，再次校验命令以已知安全工具前缀开头（与 `personalize` 落盘时同一套判定）。`rm -rf .`、`curl …` 这类\"无元字符但任意可执行文件\"以及 `python <任意可执行文件> -m <安全工具>`（中间夹带脚本）都不再通过；`python -m` 仅当 `-m` 为解释器之后的第二个 token 才被识别为模块调用。安全前缀新增 `dart`/`flutter`/`mix`/`bundle`/`ruby`/`true`/`false`/`exit`。\n- **手写配置不再触发崩溃**：`onboarding:` 为标量/列表、`personalization` 非 dict、`validation.commands` 非 dict、`language: null` 或非 `zh`/`en` 等手写/漂移污染的配置，在 `status`/`fingerprint`/`refresh`/`show`/`wizard`/`config set` 中一律安全降级或显式拒绝，不再抛 `AttributeError`/写坏结构。\n- **install.py 供应链加固**：跨主机重定向时剥离 `Authorization` 头（`_SafeRedirectHandler`/`_urlopen`）；GitHub API 响应按块读取并加字节上限；`_safe_extractall` 在解压前校验单成员 ≤256MiB、总量 ≤500MiB（解压炸弹防护）；`copy_skill_files` 拒绝经符号链接祖先目录写入，并修复文件/目录类型冲突（过期文件挡住目录、过期目录挡住文件）。\n- **install 无操作不再报成功**：非交互 stdin、所有目标均已存在且未给 `--force` 时返回退出码 1（与 uninstall 无操作契约一致），npx 包装层可据此区分\"已安装/已刷新\"与\"什么都没发生\"；uninstall 在非交互 stdin 下拒绝未经确认的删除。\n- **npm 安装器**：`askYesNo` 在 stdin EOF 或 30s 超时后回落到默认值（不再挂死）；`parseChecksums` 跳过非 64 位十六进制摘要、拒绝同一 basename 的冲突摘要（防篡改）、兼容 `#` 注释行；`-h`/`--help`/`-v`/`--version` 短路解析（后面跟坏参数也不再报错）；`package.json` 增加 `files` 白名单并移除全局 `iterate` bin（避免与真实 CLI 冲突）。\n- **validate.py**：JSON Schema 文件本身结构损坏（坏 `$ref`/`$defs`、类型错误）时报出 \"Invalid JSON Schema\" 诊断而不是未捕获 traceback 崩溃。\n- **config set 嵌套保护**：点号路径的中间段为标量/列表时明确拒绝写入（不静默替换成 mapping）；`.configset` 备份文件名追加随机盐，同一秒内多次 `config set` 不再互相覆盖备份。\n- **doctor dimension_sets**：非字符串的集合名与混合类型 dimension 条目不再让 `sorted()`/正则崩溃，统一归一化后上报。\n\n### 测试 / Tests\n\n- 全量 Python 测试 1001 个全部通过，`ruff check .` 通过，npm 安装器测试通过：\n - `test_install_script.py`：符号链接祖先拒绝 / 类型冲突 / 超大成员 / 总量超限 / 非交互无操作返回 1。\n - `test_guard.py`：未知前缀命令拒绝 / 已知安全命令放行。\n - `test_onboarding.py`：`validation.commands` 非 dict 归零、`language` 非法值回退默认。\n - `test_drift_ignore.py`：标量 `onboarding` 在 status/refresh 路径安全降级。\n - `test_config.py`：中间段标量拒绝覆盖、备份名加盐不冲突。\n - `test_validate.py`：损坏 JSON Schema 本身被诊断而非崩溃。\n - `test_publish_qoder.py`：默认 `--out` 构建不再向仓库工作树泄漏 zip。\n\n---\n\n## [3.2.0] — 2026-09-06\n\n### 新增 / Features\n\n- **`iterate refresh --json` / `--dry-run --json`**（B1）：refresh 增加结构化 JSON 输出——`--dry-run --json` 预览而不写盘，`--json` 先预览后写入；负载含 `ok`/`dry_run`/`changed`/`config_changed`/`md_changed_lines`/`stats` 与失败时的 `error`，供脚本/CI 消费。\n- **`iterate doctor --strict`**（B2）：新增 `--strict` 标志，将 warning 一并视为失败（退出码 1），供 CI 在\"非全绿即失败\"的门禁场景使用；默认仍仅 error 阻塞，`--json` 下同样生效。\n- **`iterate status --json` 漂移明细**（B4）：结构化输出新增 `drift_detected`（布尔或 null）及 `drifted_added`/`drifted_removed`/`drifted_changed` 明细列表，脚本不再需要解析人类可读的 summary 字符串。\n- **`iterate config` 点号路径别名**（B5）：`set`/`get` 支持嵌套点号键（如 `config set git.use_worktree true`、`reviewer.coverage_validation false`），与 `iterate show` 的路径表达及手写配置习惯保持一致；JSON 输出统一以规范扁平键返回。\n- **doctor 新增 ITERATE.md USER-OWNED 标记检查**（B6）：`iterate refresh` 会在标记缺失时拒绝覆盖（防手写内容丢失），此前只在 refresh 时才暴露；doctor 新增 `iterate.md.markers` 检查在诊断阶段提前告警，建议 `iterate reonboard` 恢复标记。同步新增 `invariants` 结构 + `invariants.commands` 元字符安全检查。\n\n### 修复 / Fixes\n\n- **doctor 白名单合规检查 fail-open**：`_check_whitelist_compliance` 此前遇到不安全白名单条目即提前返回，跳过命令级 shell 元字符扫描（`pytest; rm -rf /` 可借坏条目绕过）；现元字符扫描无条件执行，两个问题都如实上报；白名单条目先 `.strip()` 再参与匹配（`\" pytest \"` 不再产生误导性 \"not in whitelist\" 警告）。\n- **doctor manifest 漂移三原因区分**：无 drift 检查时按\"配置不可读 / drift_check 已禁用 / 尚未录制指纹（建议 `iterate refresh`）\"分别说明，不再笼统报\"不适用\"。\n- **`doctor --fix` 补录缺失指纹（B3）**：对已 onboarded（录音含 skill_version）但 `fingerprints` 为空的配置，`--fix` 现在补录当前 manifest 指纹，恢复漂移检测；已有指纹原样保留。`--fix` 失败时给出明确原因（缺配置/配置损坏），`--json` 下输出与 DoctorReport 同构的失败负载。\n- **`doctor --fix --json`、`--json-out`、`fingerprint --json` 输出修正**：`--fix` 失败改输出 DoctorReport 形状 JSON；`--json-out` 与 TUI 模式结合时也保留 `fixes`；`fingerprint verify --json` 的 `reason` 精确到未 onboarding / 已禁用 / 无指纹三类。\n- **CLI 语义修正**：裸 `iterate`（无子命令）退出码由 0 改为 2（使用错误）；`iterate --version` 在非 TTY（管道）下输出纯 `iterate X.Y.Z` 便于解析；`--json` 对交互式命令（`onboard`/`personalize`/`reonboard`）改为明确拒绝（退出码 2）而非静默吞掉。\n- **健壮性兜底（防手写配置崩溃）**：`check_drift` 对脏指纹条目加 `isinstance(dict)` 守卫；`personalize` 加载 `risk_areas`/`known_intentional`/`dimension_focus` 时对非 list 标量不再逐字符迭代；`guard pre-check` 对多个缺失 manifest 全部上报而非只报第一个。\n- **refresh 配置与 diff 统计**：空 `command_whitelist` 不再写为 `command_whitelist: []`（schema minItems 1 违例）而是删除该键；`_diff_stats` 改用 `SequenceMatcher` opcode 长度统计，内容行恰好以 `--`/`++` 开头时不再被误吞为 `--- `/`+++ ` 文件头。\n- **wizard**：`_run_basic_wizard` 保留既有 `reasoning_effort`（不再重设默认）；`_parse_dimension_selection` 逐项丢弃非法选择而非整组回退（仍保证全非法输入返回 `[]`）。\n- **configcmd 非 mapping 拒绝覆盖**：顶层 YAML 为列表/标量（如手写 `- a`）时 `config set` 明确拒绝并原样保留，不再静默回填成 `{}` 后再写入覆盖。\n- **publish_qoder.py**：未传 `--out` 时 zip 默认落到当前目录（此前落在临时目录随上下文退出被删除，构建结果凭空消失）；`_copy_tree` 与 git-archive 路径在 dotfile 上保持一致（只排除 `.git` 与显式 excludes；支持顶层文件），zip 条目排序确定化（同源重复构建产生字节一致的产物）。\n- **下载/校验安全**：`update_downloads_badge._read_bounded` 改为按 EOF 循环读取（单次 `read` 可能回不足量，此前可绕过字节上限）；`install.py` 与 `installer.js` 的校验和比较改用常量时间比较（`hmac.compare_digest` / `crypto.timingSafeEqual`）；`installer.js` 增加 `--max-filesize` 字节上限、PAT 仅附加给 `api.github.com`（release-asset 公开下载不再携带令牌）、`--fail-with-body` 按 curl 版本回退为 `--fail`。\n\n### 测试 / Tests\n\n- 新增 35 例，全量 Python 测试 970 个全部通过，`ruff check .` 通过，npm 安装器测试通过：\n - `test_doctor.py`：白名单 fail-open / 空白条目匹配 / 条目字符网（3）、drift 禁用与无指纹原因（2）、invariants 结构/命令/ensure（4）、ITERATE.md 标记（2）、`render_report` strict（3）、`run_doctor_fix` 补录指纹（2）。\n - `test_guard.py`：多缺失 manifest 全量上报与混合场景（2）。\n - `test_refresh_reconcile.py`：`_diff_stats` 头部伪鉴别/变更总数（3）、空白名单删键（2）。\n - `test_config.py`：点号别名 set/get（4）、非 mapping 拒绝覆盖（2）、CLI 别名（1）。\n - `test_onboarding.py`：`_parse_dimension_selection` 部分非法保留/去重/空白（3）。\n - `test_publish_qoder.py`：默认 out 存活 / 确定性 zip / dotfile 一致性 + 顶层文件复制（3）。\n - `npm-installer/test/mode.test.js`：`isGithubApiUrl` 令牌作用域（5）。\n- 更新既有断言以匹配新语义：裸 `iterate` 退出码 0→2；badge `_FAKE_RESP` 与 SkillHub `FakeResp` 改为位置感知 + EOF 语义（真实 `read()` 行为）。\n\n### 内部 / Internal\n\n- `version` 升至 3.2.0（minor：新增 B1/B2/B4/B5/B6 特性 + 修复批次）。\n\n---\n\n## [3.1.0] — 2026-09-05\n\n### 新增 / Features\n\n- **CLI `iterate fingerprint verify`**：新增指纹校验子命令，比对 `iterate.config.yaml` 记录的 manifest SHA-256 指纹与当前项目根的实际状态，检测技术栈 manifest 的新增/删除/变更（与 `iterate status` 漂移检测共享 `check_onboarding_drift` 逻辑）；退出码 0 = 无漂移，1 = 存在漂移（漂移非阻塞，附 `iterate refresh` 建议）；支持 `--json` 结构化输出（新增/删除/变更/未变清单）。\n- **`iterate doctor` 错误摘要带通过计数**：存在错误时汇总行由 `Doctor: N error(s) found.` 升级为 `Doctor: N error(s) found (M check(s) passed).`，一次看清有多少检查通过（仅 warnings 与 clean 路径行为不变）。\n\n### 修复 / Fixes\n\n- **`_cmd_personalize` 写入错误兜底**：`save_personalization` 除 `CorruptConfigError` 外还可能抛 `OSError`/`UnicodeDecodeError`（磁盘满、权限不足、非 UTF-8 路径等），此前会冒泡成原始 traceback；现统一捕获并显示友好错误、退出码 1。\n- **wizard 读取既有配置改用 `load_config_strict`**：`_load_existing_onboarding_data` 原先用裸 `yaml.safe_load`，损坏的 YAML 会被静默当作\"空配置\"继续合并。现改用 `load_config_strict` 明确报错；非 mapping（如裸列表）的配置返回 None 而非静默吞掉。\n- **`doctor` 配置解析区分\"缺失/损坏/不可读\"**：`_check_config_parse` 改用 `load_config_strict`，损坏的 `iterate.config.yaml` 不再笼统报\"缺失或不可解析\"，而是给出具体 YAML 语法错误定位。\n- **`suggest_validation_commands` 不再硬编码 `tests/` 目录**：Python 项目建议的 `pytest` 命令按实际扫描到的测试目录（`tests`/`test`/`__tests__`/`spec`）生成，项目用 `test/` 时不再给出一条必然失败的默认命令。\n- **`FORBIDDEN_COMMAND_CHARS` 改为 `frozenset`**：与 `doctor.py`/`guard.py` 的 `COMMAND_METACHARS` 保持一致，获得 O(1) 成员判定（成员检查在命令校验热路径上）。\n\n### 测试 / Tests\n\n- 新增 7 例：`tests/test_drift_ignore.py::TestFingerprintVerifyCli`（6 例：无漂移退出码/输出、变更退出码 1、删除 manifest、未 onboarding 优雅降级、`--json` 无漂移/有漂移负载字段）；`tests/test_doctor.py::TestRenderSummary::test_errors_report_passed_check_count`（错误路径汇总行含通过计数）。\n- 更新 2 例以匹配新错误形态：`test_load_existing_onboarding_data_logs_error`、`test_returns_none_on_yaml_list`（wizard 改用 `load_config_strict` 后的错误文案/空配置判定）。\n- 全量 Python 测试 935 个全部通过（既有 928 + 新增 7），`ruff check .` 与 `mypy iterate_cli` 均通过。\n\n### 内部 / Internal\n\n- wizard 返回用户流程（`_load_existing_onboarding_data`）的 `scan_project` 调用纳入 `tui.status(...)` 进度上下文，与首次基础配置流程的扫描反馈保持一致。\n\n---\n\n## [3.0.1] — 2026-09-03\n\n### 修复 / Fixes\n\n- **`guard pre-check` 空验证命令 fail-closed**：对*已 onboarded*（存在非空 `iterate.config.yaml`）但 `validation.commands` 为空的项目，`guard pre-check` 不再返回 `PASS`/退出码 0（此前会给出\"可以开工\"绿灯，而其承诺的 `post-check` 必然失败）。现按 fail-closed 契约改为 `FAIL`/退出码 1，提示先补配置 `validation.commands`，使 pre-check 与 post-check 的退出码语义一致；全新项目（尚无配置）仍正常降级放行。SKILL.md 防御式模式章节同步说明该行为。\n- **npm 安装器与 install.py 的校验和 `*` 前缀剥离语义统一**：`installer.js::parseChecksums` 原先用 `replace(/^\\*/, '')` 仅剥离一个前导 `*`，而 Python `scripts/install.py::_parse_checksum` 用 `lstrip(\"*\")` 剥离全部前导 `*`，破坏了\"两处同步\"的既定声明。现统一为剥离全部前导 `*`（`/^\\*+/`），并新增 `**` 前缀的边界断言。\n\n### 测试 / Tests\n\n- 新增 `tests/test_release_meta.py`（2 例）：绑定 `pyproject.toml` / `iterate_cli/__init__.py` / `SKILL.md` frontmatter / `npm-installer/package.json` 四处版本号必须一致且为 `X.Y.Z` 语义化版本，防止 post-patch 发版漏改某处导致跨分发渠道漂移。\n- `tests/test_guard.py` 新增 2 例：已 onboarded 但无 `validation.commands` 的配置、显式空 `commands` 映射，`guard pre-check` 均 fail-closed。\n- `npm-installer/test/mode.test.js` 新增 1 例：多前导 `*` 校验和标记按 `lstrip(\"*\")` 语义剥离。\n- 全量 Python 测试 928 个全部通过（既有 924 + 新增 4），`ruff check .` 通过，npm 安装器测试通过。\n\n### 内部 / Internal\n\n- `pyproject.toml` build-system 依赖精确定版本：`setuptools>=68.0` → `setuptools==68.0.0`、`wheel` → `wheel==0.42.0`。\n\n---\n\n## [3.0.0] — 2026-09-03\n\n### 新增 / Features\n\n- **双模式：iterate 原模式 + 防御式编程模式**（v3.0 大版本主线）：SKILL.md 新增防御式编程模式（`/iterate defensive`），面向**用户让 AI 做正常增量式编程任务**（新增功能、修 bug、重构、接入 API、补测试）——宿主 AI 从动手前到收尾**从头至尾贯彻防御式编程理念**：① 动手前（声明假设 + 前置校验）→ ② 动手时（信任边界验证 + 最小步进）→ ③ 动手后（每步后置校验）→ ④ 收尾（不变量守护 + iterate 收敛门禁，**不收敛不交付**）。iterate 原模式（`/iterate`）行为与 v2 完全一致，零回归，默认不变。\n- **CLI `iterate guard pre-check [paths...]`**：动手前确定性前置校验——目标路径存在、git worktree 干净、依赖 manifest 就绪、验证命令配置安全；退出码 0 = 可以开工，1 = 禁止开工；支持 `--json` / `--dry-run`。\n- **CLI `iterate guard post-check [module...]`**：动手后后置校验——精确执行 `validation.commands.`（运行时唯一权威白名单，不拼装不前缀）；退出码 0 = 本次改动安全，1 = 必须先修复或回滚；支持 `--json` / `--dry-run`。\n- **CLI `iterate invariant`**：项目级不变量检查——`invariants.ensure` 文件断言 + `invariants.commands` 命令列表；无 `invariants` 段时自动退化为 `validation.commands`（旧配置零破坏）；退出码 0 = 不变量成立，1 = 存在违反项；支持 `--json` / `--dry-run`。\n- **配置 `mode: iterate | defensive`**：`iterate.config.yaml` 新增默认执行模式配置项（默认 `iterate`，零破坏），可用调用参数显式 `defensive` 覆盖；`iterate show` / `iterate config get|set mode` 支持读写。\n- **配置 `invariants` 段**：`iterate.config.yaml` 新增 `invariants`（`ensure` 文件断言 + `commands` 精确命令列表），与 `validation.commands` / `command_whitelist` 共用安全基线（白名单校验、元字符防护）；`config/config.schema.json` 与随包分发副本同步扩展。\n\n### 测试 / Tests\n\n- 新增 `tests/test_guard.py`（33 例）：pre-check / post-check / invariant 的正常路径、异常路径（目标缺失、manifest 缺失、命令失败、脏 worktree、损坏配置）与边界场景（无参数、空配置、模块过滤、dry-run 预览、invariants 退化到 validation.commands、JSON 输出与退出码、运行时元字符拒绝、未配置模块报告），并覆盖 CLI 集成（`guard` / `invariant` 子命令的 `--json` 与退出码契约）。\n- 全量 Python 测试 924 个全部通过（既有 888 + 新增 36），`ruff check .` 通过。\n\n---\n\n## [2.12.0] — 2026-09-02\n\n### 新增 / Features\n\n- **`iterate config --json` 结构化输出**：非交互式配置命令新增 `--json`，供脚本/CI 场景消费——`iterate config --json` 输出全部可设键的 JSON 对象、`iterate config get KEY --json` 输出 `{\"KEY\": value}`、`iterate config set KEY VALUE --json` 成功时输出 `{\"key\": KEY, \"value\": <解析值>}` 确认对象；stdout 保持纯净（错误仍走 stderr + 非零码），与 `iterate status/show/doctor --json` 契约对齐。\n\n### 修复 / Fixes\n\n- **publish_qoder 安全加固**：`_git_archive_extract` 原先用 `os.system(\" \".join(cmd))` 经 shell 执行 `git archive`，`--exclude` 用户输入被无引号拼入命令字符串，存在 shell 注入面。现改用 `subprocess.run(check=False)` 列表形式（不启动 shell）并以真实返回码判定；解压由裸 `archive.extract` 改为 `archive.extractall(members=_safe_members(...))`，`_safe_members` 拒绝绝对路径、`..` 越界、重复成员及逃逸目标目录的符号链接（zip-slip 防护，与 `install.py` 安全基线一致）。\n- **install 下载根目录选择更稳**：`_download_release_source` 原返回 `extracted[0]`（临时目录迭代首个子目录），多顶层目录时可能选中非 skill 目录。现要求 release tarball 顶层目录中恰好一个含 `SKILL.md` 标记，否则拒绝并报错返回。\n\n### 测试 / Tests\n\n- 新增 `tests/test_publish_qoder.py::TestSafeMembers`（6 例：正常嵌套成员、`..` 越界、绝对路径、重复成员、逃逸符号链接、目录内安全符号链接）。\n- 新增 `tests/test_install_script.py::TestDownloadReleaseSource`（3 例：唯一含 SKILL.md 根被选中、无标记根拒绝、多标记根拒绝）。\n- 新增 `tests/test_config.py::TestConfigJson`（5 例：单键 get、全键 list、set 确认且 stdout 纯净、未知键报错、run_config_get 直调）。\n- 全量 Python 测试 888 个全部通过，`ruff check .` 通过。\n\n---\n\n## [2.11.2] — 2026-09-01\n\n### 修复 / Fixes\n\n- **refresh 调和结果真正落盘**：`iterate refresh` 原本计算出的新增 `validation.commands`、`command_whitelist` 前缀与 `dimension_sets` 调和结果只用于重渲染 `ITERATE.md`，未写回 `iterate.config.yaml`，导致配置与文档跑偏。现将 `_build_refreshed_config` 改为接收完整 `OnboardingData`，把调和后的 dimension_sets / validation.commands / command_whitelist / reasoning_effort 等一并持久化，同时保留用户既有自定义字段（如自定义命令逐字保留、显式空白名单意图不覆写）。\n- **doctor 畸形白名单不再绕过元字符安全网**：`command_whitelist` 为非法形态（如裸字符串 `make`）时，原先跳过了白名单合规校验，且独立的 shell 元字符安全网仅在白名单为 `None` 时运行，导致 `make; rm -rf /` 这种命令可能通过健康门禁。现检测到非法白名单时仍调用元字符检查，安全网不再被绕过。\n- **wizard 重跑基础配置不再丢弃数据**：返回用户拒绝更新基础配置、但现有配置无法加载时，重新运行完整基础向导并确认的新数据，若随后未再个性化，会被「全部拒绝/无变更」守卫丢弃导致白做。现在重跑基础向导即视为\"更新基础配置\"，新采集的数据会正常写入。\n- **validate.py 重定义区块切分双重偏移**：`_sections_for_redefinition` 用 `content[match.start():][start:]` 切分，第二次切片偏移作用在已裁剪子串上造成偏移叠加，长前置文本会跳过区块内部终止标题、让其越界吞并后续内容。改为 `content[start:]`（`start == match.end()`）直接切分，块边界正确停在下个 `## `/`### ` 标题前。\n- **publish_qoder 幂等标记字符不一致**：依赖自包含说明段的幂等守卫检测单空格 ``，而写入时经两次 `replace()` 得到双空格版本，导致复用已标注 `SKILL.md` 重建时重复追加。现直接嵌入 `_DEP_MARKER` 原样，重复构建幂等。\n\n### 内部 / Internal\n\n- `iterate_cli/refresh.py::_build_refreshed_config` 签名由 `(existing_config, new_fingerprints)` 改为 `(existing_config, data: OnboardingData)`；局部用具名拷贝替换 `**dict` 解包以消除 mypy type 错误。\n\n### 测试 / Tests\n\n- 新增 `tests/test_refresh_reconcile.py::TestIncrementalRefreshPersistsReconciledData`（4 例：命令/白名单落盘、dimension_sets 落盘、_build_refreshed_config 直接同步、自定义命令保留）。\n- 新增 `tests/test_validate.py::TestSectionsForRedefinition`（2 例：块止于下个三级标题、两个连续重定义块互不吞并）。\n- 新增 `tests/test_publish_qoder.py`（2 例：幂等标记逐字一致、普通文件仅追加一次）。\n- 全量 Python 测试 874 个全部通过，`ruff check .` 通过。\n\n---\n\n## [2.11.1] — 2026-08-31\n\n### 修复 / Fixes\n\n- **偏门范围重定义「禁抄预设」**：`SKILL.md` Phase 0 明确——未命中任何命名维度集的 goal，必须从根（维度全集）重新推导维度方案，禁止以全局 `dimensions` 或任一已有维度集为起点筛选/微调；每个选中维度必须给出本范围特有的独立理由（与某预设集雷同即视为套用、推翻重想），并可新增非标准临时维度。范围路由（命中预设）与重定义（未命中）两条路径彻底分离，防止 AI 惰性沿用预设。\n\n### 新增 / Features\n\n- **`scripts/validate.py decisions` 新增重定义记录机器校验**：`.iterate_decisions.md` 中出现 `### Scope Dimension Redefinition (on-the-fly)` 小节时，强制要求 `**Origin scope:**` 与 `Dimension / Independent reason` 表格，且每个维度的理由不得照抄 `config/dimensions/.yaml` 默认 focus（去空白/大小写归一化后比对）。为「禁抄预设」提供可执行的第二道闸。决策日志模板同步新增该小节示例。\n\n### 内部 / Internal\n\n- `pyproject.toml` 的 ruff `extend-exclude` 收录 `.awesome-claude-skills`（第三方 marketplace 校验用 submodule，本地检出会导致 `ruff check .` 假阳性，CI 未检出子模块不受影响）。\n\n### 测试 / Tests\n\n- 新增 `tests/test_validate.py::TestValidateScopeRedefinitions`（8 例：缺 Origin / 空 Origin / 理由抄默认 focus / 理由为空 / 缺表头 / 无数据行 / 合法通过）；全量 Python 测试 862 个全部通过，`ruff check .` 通过。\n\n---\n\n## [2.11.0] — 2026-08-31\n\n### 新增 / Features\n\n- **范围审查蓝图 `dimension_sets`**：新增「按审查范围预设的维度集」能力。用户在 onboarding 时可按 `frontend` / `api` / `security` / `performance` / `style-tes...","readmeExcerpt":"Skill: Iterate Owner: jingzhao-l Summary: Fully automated multi-round code iteration with configurable N-dimension parallel review, onboarding/personalization, and a cross-assistant installer/update system with mandatory SHA256 checksum verification. v3.0 adds a dual-mode (the original iterate mode plus a defensive-programming mode via /iterate defensive) that performs normal incremental coding tasks with defensive d","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"Step 0 — Onboarding Check\n └─ Locate project root → check ITERATE.md → drift detection → (onboard if needed)\n\nSetup\n └─ Extract goal → load config → read project context (ITERATE.md → CLAUDE.md → …) → create isolated branch/worktree\n\nLoop (round = 1 .. max_rounds)\n ├─ Phase 0: Dimension Planning (route goal → dimension_sets | ad-hoc redefine, bounded record)\n ├─ Phase 1: N-dimension parallel review (N = enabled dimensions count, default 9)\n ├─ Phase 2: Atomic fixes (direct)\n ├─ Phase 3: Architectural fixes (approval → serial sub-agents)\n ├─ Phase 4: Record round results\n └─ Phase 5: Validate → merge → push\n\nSummary"},{"language":"bash","snippet":"iterate onboard # 交互式向导（多路引导：首次/非首次自动分支）\niterate personalize # 个性化配置（项目中途追加约束，9 步向导）\niterate personalize --clear [--yes] # 清空所有个性化配置（结构化规则 + ITERATE.md 相关段落）\niterate show # 只读查看合并后的配置与个性化详情（支持 --json）\niterate refresh # 增量刷新（保留用户手写区；支持 --json / --dry-run --json 结构化报告）\niterate reonboard # 完整重新 onboarding（备份旧文件）\niterate doctor # 项目健康诊断（onboarding/config/维度/漂移等全项检查；--strict 将 warning 一并判失败；--fix 安全修复；--json / --json-out 结构化输出）\niterate status # 查看 onboarding 状态和漂移检测（--json 含 onboarded、config_exists/config_ok、drift_detected 与明细列表）\niterate guard pre-check [targets...] # 编辑前静态校验（目标存在/工作区干净/manifest 就绪；只读，从不执行命令；--json）\niterate guard post-check [targets...] # 编辑后执行 validation.commands 并核对结果（--dry-run 只预览命令不执行；--json）\niterate invariant # 项目级不变量校验（--dry-run 预览；--json）\niterate fingerprint verify # 校验 manifest 指纹漂移（--json）\niterate config # 非交互式查看全部可设配置值（支持 --json）\niterate config get # 读取单个配置项的解析值（支持 --json，输出 {\"key\": value}）\niterate config set # 校验并写回单个配置项（自动备份；--json 输出确认对象）\niterate update # 自更新：SHA-256 校验后刷新助手技能目录 + 重装 CLI（--check 只对比版本；--yes 跳过确认；--assistants 限定刷新范围，未知助手名报错而非静默跳过）"},{"language":"text","snippet":"round = 1\nwhile round <= maxRounds:"},{"language":"text","snippet":"phase plan → 获取审查计划（维度、reviewer prompt、findings schema、round cap）\nknownAng = [] → 跨轮累计已发现 findings（供 reviewer 只找新问题）\nrounds = [] → 原始每轮 findings\nfor r in 1..cap:\n # 每个维度一个并行 reviewer，只报 NEW 问题\n raw = parallel(每个维度 → review 该维度, 已知 = knownAng)\n rounds.push({ round: r, findings: raw })\n knownAng.push(...raw)\n # 确定性收敛判定：aggregate 后本轮新 findings 数\n conv = aggregate(rounds) # 汇总去重/排序/每轮新发现数\n if conv.findingsByRound[r-1] == 0: break # 收敛\nphase report → finalReport = aggregate(rounds) # 最终审查报告\nphase meta-review → metaReview = meta-review(finalReport) # 审查报告本身：校验内部一致性\nreturn { rounds, converged, findingsByRound, totalFindings, bySeverity, byDimension,\n report: finalReport,\n metaReview: { verdict, issues, checksRun },\n finalReport }"},{"language":"text","snippet":"Review the codebase for {DIMENSION} issues ONLY.\n\nScope: {review.scope}\n- \"full\" → review the ENTIRE codebase.\n- \"changed-only\" → review ONLY files changed in the current round (git diff against {git.target_branch}).\n- 当 `review.scope` 为 `changed-only` 且本轮相对于 `target_branch` 无改动文件时，自动 fallback 为 `full`。\n\nEVIDENCE RULE (mandatory): read every file you report on with the read_file tool\nBEFORE judging it. You must NEVER report a location you did not actually read —\nspeculation about code you never inspected is a disqualifying failure, and\nfabricated line numbers are treated as poisoned evidence. Anchor every finding\nto real, read code.\n\nCOVERAGE RULE (mandatory): below is the exact file inventory you are assigned\nto review. You MUST open EVERY file in this inventory with the read_file tool\nbefore judging it — do not skip, skim-declare, or assume any file without\nreading it. Files you did not actually open are considered un-reviewed and\nwill lower your coverage score. Return a `readFiles` array listing every file\nyou actually opened.\n\nAssigned file inventory: {assignedFileInventory}\n\nFocus: {focus description}\n\nProject context: {projectContext}\n\nFor each finding, report:\n- file, line (REQUIRED positive integer for anchored, line-targeted issues —\n the exact line you READ; use 0 for whole-file/module-level issues),\n severity (critical/high/medium/low)\n- dimension, summary, failure_scenario, suggested_fix\n- is_atomic (boolean): true if fix is ≤{atomic.max_lines} lines within a SINGLE function/file;\n false if cross-file, new files, API changes, or large refactoring.\n\nReturn strictly as JSON: { \"findings\": [...], \"readFiles\": [...] }\nEach finding object must contain: file, line, severity, dimension, summary, failure_scenario, suggested_fix, is_atomic.\n`readFiles` must list every file in the assigned inventory you actually opened with read_file.\nIf no issues are found, return { \"findings\": [], \"readFiles\": [...] }."},{"language":"text","snippet":"> Focus: {focus description}\n> \n> Extra focus (from personalization): {personalization.dimension_focus[dimension].focus}\n>"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: iterate\nslug: iterate-skill\ndisplayName: Iterate\ndescription: Fully automated multi-round code iteration with configurable N-dimension parallel review, onboarding/personalization, and a cross-assistant installer/update system with mandatory SHA256 checksum verification. v3.0 adds a dual-mode (the original iterate mode plus a defensive-programming mode via /iterate defensive) that performs normal incremental coding tasks with defensive discipline end-to-end.\nversion: 3.4.4\npermissions:\n file_read: true\n file_write: true\n shell: true\n git: true\n network: \"github.com only (release tarball + checksum verification)\"\n sensitive_files:\n skip: [\".env\", \".env.*\", \"*.key\", \"secrets/\", \"*.pem\", \"*.p12\", \"*.crt\", \"*.cer\", \"credentials.json\", \".aws/\", \".ssh/\"]\n---\n\n# /iterate `` `[rounds]` `[no-limit]`\n\n# /iterate defensive ``（防御式编程模式 / Defensive-Programming Mode）\n\n> **面向人类读者**：本文件是供 AI 助手消费的 Skill 指令。若您是开发者或浏览者，欢迎前往 GitHub 仓库 [jingzhao-l/iterate-skill](https://github.com/jingzhao-l/iterate-skill) 阅读 README，详细了解本 Skill 及其附属生态（iterate-harness、iterate-plugin、CLI 等）。\n>\n> **For human readers (English)**: This file is a Skill manifest consumed by AI assistants. If you are a developer or a human visitor, welcome to the GitHub repository [jingzhao-l/iterate-skill](https://github.com/jingzhao-l/iterate-skill) — read the README to learn more about this Skill and its ecosystem (iterate-harness, iterate-plugin, CLI, etc.).\n\n---\n\n## 简介 / Overview\n\n> 中文：全自动多轮代码迭代。每轮从 N 个已启用维度并行审查整个项目（默认 9 个），原子问题直接修复，架构问题经用户批准后由子代理串行执行，验证通过后（合并与推送为 opt-in，默认关闭）循环直到零 findings 或达到轮数上限。\n>\n> English: Fully automated multi-round code iteration. Each round launches N parallel dimension reviewers across the project (default 9), fixes atomic issues directly, executes architectural issues after user approval via serial sub-agents, validates, and loops until zero findings or max rounds (merge/push are opt-in and disabled by default).\n\n**v3.0 双模式 / v3.0 dual-mode**：本 Skill 现为**双模式**——\n\n- **iterate 模式**（原 `/iterate`，默认，v2 全部能力完整保留）：审查 → 修复 → 验证 → 收敛闭环。\n- **防御式编程模式**（新增 `/iterate defensive`）：面向**用户让 AI 做正常增量式编程任务**的场景（新增功能、修 bug、重构等），宿主 AI 从动手前到收尾**从头至尾贯彻防御式编程理念**（四步协议：pre-check → 最小步进编码 → 每步 post-check → invariant + iterate 收敛门禁），以 iterate 闭环收尾作为**交付门禁**（不收敛不交付）。\n\n> Defensive-Programming Mode (v3.0, via `/iterate defensive`): for the scenario where the **user asks the AI to do a normal incremental coding task** (add a feature, fix a bug, refactor). The host AI performs that task end-to-end with defensive discipline — a four-step protocol: `pre-check` before touching anything → minimal-step editing (validate at the trust boundary) → `post-check` after every edit → `invariant` + the iterate convergence loop as a **delivery gate** (no convergence, no delivery).\n\n---\n\n## 何时使用 / When to Apply\n\n**iterate 模式**适用于以下场景：\n\n- 需要系统性提升代码质量、修复潜在 bug 或安全漏洞。\n- 项目进入重构、迭代收尾或发布前的审查阶段。\n- 需要多维度（正确性、安全、性能、架构等）并行审查。\n- 希望将原子问题自动修复，将架构问题经审批后修复。\n\n**防御式编程模式**（`/iterate defensive`）适用于**用户让 AI 做正常增量"},{"path":"npm-installer/README.md","content":"# iterate-skill-installer\n\n

\n English ·\n 简体中文\n

\n\nOne-command installer for [iterate-skill](https://github.com/jingzhao-l/iterate-skill) across AI coding assistants.\n\n[![GitHub stars](https://img.shields.io/github/stars/jingzhao-l/iterate-skill?style=social&label=Star)](https://github.com/jingzhao-l/iterate-skill)\n\n> ⭐ If this project helps you, please consider giving a GitHub star — it means a lot to open-source maintenance!\n\n## Usage\n\n```bash\n# Interactive install — detects your AI assistants and lets you choose\nnpx iterate-skill-installer\n\n# Install to a specific assistant only\nnpx iterate-skill-installer --ai trae\nnpx iterate-skill-installer --ai claude\n\n# Install into a project directory instead of globally\nnpx iterate-skill-installer --target ./my-project\n\n# Force overwrite existing skill files\nnpx iterate-skill-installer --force\n\n# Skill-only install — skip installing the iterate CLI\nnpx iterate-skill-installer --no-cli\n\n# Show help / version\nnpx iterate-skill-installer --help\nnpx iterate-skill-installer --version\n```\n\n## What it does\n\n1. Checks for Python 3 on your system.\n2. Fetches the latest iterate-skill release from GitHub.\n3. Downloads the release tarball and `SHA256SUMS.txt`.\n4. Verifies the tarball checksum.\n5. Extracts the release into a temporary directory.\n6. Runs the bundled Python install script (`scripts/install.py`) which:\n - Detects installed AI coding assistants on your machine.\n - Prompts you to select targets (default: all detected assistants).\n - Copies the skill files into the correct skills directories.\n7. Installs the `iterate` CLI onto your PATH (prefers `pipx`, otherwise\n `pip install --user`) so you can run `iterate onboard` directly.\n\n> **Note:** the installer normally puts the `iterate` CLI on your PATH so a single\n> command gives you both the skill and the CLI. If you **don't** want the CLI\n> auto-installed, pass `--no-cli` to install the skill only — you can install the\n> CLI later with `pipx install .` or `pip install .` from a checkout. If the CLI\n> install fails, you can still install it later the same way.\n\n## Supported AI assistants\n\nTrae, Claude / Claude Code, Cursor, Windsurf, GitHub Copilot, Codex, Gemini CLI, OpenCode, Aider, AiderDesk, Zed, Warp, Continue, Cline, Roo Code, Qoder, Augment, OpenClaw, Autohand Code CLI, IBM Bob, CodeArts Agent, Antigravity, Amp, Deep Agents, Kimi Code CLI, Astral.\n\n## Requirements\n\n- Node.js 18+\n- Python 3.10+\n- `tar` command available on PATH (available by default on macOS, Linux, Windows 10+)\n\n## Release tarball structure\n\nThe GitHub release asset `iterate-skill.tar.gz` must contain **exactly one\ntop-level directory** (e.g. `iterate-skill/`). The installer extracts it with\n`tar --strip-components=1`, so a tarball with multiple top-level directories,\nor with entries whose path disappears after stripping the top level, is\nrejected instead of being silent"},{"path":"README.md","content":"# Iterate Skill\n\n> **English** · [简体中文](./README.zh-CN.md)\n\n
\n A portable, configurable AI coding assistant skill: fully automated multi-round code review and fixing.\n
\n\n
\n\n

\n \n \"Total\n \n

\n\n

\n \"ClawHub\"\n \"SkillHub\"\n \"npm\"\n \"License\"\n \"GitHub\n \"GitHub\n

\n\n> Want to support this project? A GitHub **Star** is the best thank-you and helps more developers discover iterate.\n\n---\n\n## Table of Contents\n\n- [About This Project](#about-this-project)\n- [At a Glance](#at-a-glance)\n- [Quick Start](#quick-start)\n- [Installation](#installation)\n- [Usage](#usage)\n- [CLI Command Reference](#cli-command-reference)\n- [How It Works](#how-it-works)\n- [Configuration](#configuration)\n- [FAQ](#faq)\n- [Security](#security)\n- [Directory Structure](#directory-structure)\n- [Contributing](#contributing)\n- [Disclaimer](#disclaimer)\n- [License](#license)\n\n---\n\n## About This Project\n\n**iterate** is an open-source project that gives AI coding assistants the ability to perform **multi-round, autonomous code review and fixing**. You don't need any background about an \"iterate\" concept — it solves a very concrete pain point:\n\n> AI assistants often \"talk a lot but do little\": a single conversation touches only a few lines, looks at one file and never re-checks the whole, a"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn72jg53khrabazt1xdtaqs8ah8awde5\",\n \"slug\": \"iterate-skill\",\n \"version\": \"3.4.4\",\n \"publishedAt\": 1791079858627\n}"},{"path":"scripts/requirements.txt","content":"# iterate-skill 校验脚本与安装脚本依赖\n# 许可证：MIT / Apache-2.0 / BSD 等宽松许可\njsonschema==4.26.0\nPyYAML==6.0.2\nrich==13.7.1"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1859,"uniquenessScore":42,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T13:00:16.526Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T13:00:16.526Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T16:34:02.360Z","emptyReason":null},"items":[{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-10T18:48:31.762Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}