reconcile

name	reconcile
description	LLM-powered standards reconciliation for a Punt Labs project
disable-model-invocation	true

Reconcile Project with Punt Labs Standards

Analyze a project against Punt Labs standards and surgically apply fixes. This command handles files that need contextual judgment — workflow customizations, CLAUDE.md quality, pyproject.toml drift — where a deterministic tool would be too blunt.

Input

If the user provided a project path as an argument, use it. Otherwise default to ..

Process

0. Detect Project

Read the project's pyproject.toml or package.json to determine:

• Language (python, node, swift, or none)
• Project type (application, library, plugin, docs)
• Whether it has an MCP server (server.py or MCP-related deps)
• Whether it has a CLI entry point ([project.scripts])

Also read the project's CLAUDE.md if it exists — it may document intentional overrides.

1. Run Deterministic Audit

Run the mechanical checks first:

punt audit <project-path>

Report the output to the user. The deterministic layer catches missing files, config gaps, and formatting issues. This command focuses on what punt audit cannot: contextual reconciliation.

2. Load Standards

Read the following files from the punt-kit standards directory. If punt-kit is a sibling directory (i.e., ../punt-kit/ relative to the project), read from the local filesystem. Otherwise, read from the punt-kit repo on GitHub.

• standards/python.md — toolchain, quality gates, project layout
• standards/github.md — CI workflows, markdownlint config, action SHA pins
• standards/cli.md — required subcommands, init rules
• standards/distribution.md — install paths, PyPI publishing
• standards/plugins.md — plugin structure (if applicable)

3. Reconcile Workflow Files

For each workflow file in .github/workflows/:

1. Read the project's current workflow

2. Read the corresponding punt-kit template from src/punt_kit/templates/workflows/

3. Identify:

   • Intentional customizations to PRESERVE: extra dependencies, cache config, system packages (e.g., ffmpeg), coverage integration, project-specific env vars, custom test commands, extra linting steps
   • Missing standard elements to ADD: new jobs, updated action versions, missing timeout settings, missing permissions declarations
   • Stale elements to UPDATE: outdated action SHA pins, deprecated syntax

4. Apply changes surgically — preserve project-specific content, add missing standard elements, update stale pins.

Decision framework for workflows:

What you see	Action
Project has extra steps not in template	PRESERVE — these are intentional
Template has steps the project is missing	ADD — explain what and why
Action versions differ (project is older)	UPDATE — with the template's version
Action versions differ (project is newer)	PRESERVE — project may have intentionally upgraded
Project has different cache/dependency config	PRESERVE — project knows its own deps
Project is missing timeout-minutes	ADD — use template's value
Template has a whole new workflow the project lacks	CREATE — but only the workflow file, not modifications to existing ones

4. Reconcile CLAUDE.md

Check the project's CLAUDE.md for:

1. Required sections present:

   • ## Standards References — with links to relevant punt-kit standards
   • ## Quality Gates — with the actual commands for this project's toolchain

2. Quality gate accuracy:

   • Compare the listed commands against what the project actually uses
   • If the project has pyright in deps but CLAUDE.md doesn't mention it, flag it
   • If CLAUDE.md lists a command the project can't run, flag it

3. Apply fixes:

   • Add missing sections (append, don't clobber existing content)
   • Update quality gates to match actual toolchain
   • Do NOT rewrite the user's custom instructions or project description

5. Reconcile pyproject.toml (Python projects only)

Compare the project's [tool.*] sections against the Python standard:

Section	Standard	Check
[tool.ruff]	line-length=88, target-version="py313"	Report if different
[tool.ruff.lint]	select includes E, F, I, UP, B, SIM, TCH	Report missing rule sets
[tool.mypy]	strict=true	Report if not strict
[tool.pyright]	typeCheckingMode="strict"	Report if not strict
[tool.pytest.ini_options]	testpaths=["tests"]	Report if missing

Do NOT auto-fix pyproject.toml — these settings affect build behavior and need human judgment. Report drift with a clear recommendation. Example:

[tool.ruff] target-version is "py312" but standard is "py313". This may be intentional if the project supports Python 3.12. Confirm before updating.

6. Report Summary

After all checks, print a structured summary:

## Reconciliation Report

### Applied (safe fixes)
- Applied: Added timeout-minutes to lint.yml
- Applied: Created release.yml from template
- Applied: Added Standards References section to CLAUDE.md

### Needs Review (human judgment required)
- Review: pyproject.toml: ruff target-version is py312, standard is py313
- Review: lint.yml: uses actions/checkout@abc123 but template uses @def456

### Already Compliant
- OK: docs.yml matches template
- OK: CLAUDE.md has all required sections
- OK: pyproject.toml tool configs are standard-compliant

Important Rules

1. Never delete project-specific content. Reconciliation is additive. If you're unsure whether something is intentional, preserve it and flag it for review.

2. Explain every change. Before applying an edit, tell the user what you're changing and why. Reference the specific standard that requires it.

3. Respect CLAUDE.md overrides. If a project's CLAUDE.md explicitly says "we use X instead of Y", that override wins. Don't flag it as drift.

4. One project at a time. Even if you can see sibling directories, only reconcile the specified project path.

5. Deterministic checks belong in punt audit. If you find yourself wanting to add a mechanical check (file exists? config key present?), note it as a potential punt audit enhancement instead.