/ase-spec-lint

name: ase-spec-lint
argument-hint: "[--help|-h] [--auto|-a] [--severity|-S=(AUTO|LOW|MEDIUM|HIGH)] [--force|-f] [--include|-i=<aspect>[,...]] [--exclude|-e=<aspect>[,...]] [--staged] [--unstaged] [<spec-reference>]"
description: >
    Lint the SpecBook-based specification (SPEC) for potential quality
    problems: its syntax, its formatting, its statements, the logical
    gaps of its model, and its completeness for an implementation.
    Use when the user wants to "lint" or "check" the "spec" or
    "specification".
user-invocable: true
disable-model-invocation: false
effort: high
allowed-tools:
    - "Bash(git rev-parse *)"
    - "Bash(git -C *)"

@${CLAUDE_SKILL_DIR}/../../meta/ase-control.md @${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md @${CLAUDE_SKILL_DIR}/../../meta/ase-dialog.md @${CLAUDE_SKILL_DIR}/../../meta/ase-getopt.md

<purpose name="ase-spec-lint"> Lint Specification </purpose>

<expand name="getopt" arg1="ase-spec-lint" arg2="--auto|-a --severity|-S=(AUTO|LOW|MEDIUM|HIGH) --force|-f --include|-i=(none|S01|S02|S03|S04|S05|S06|S07|S08|S09|S10)... --exclude|-e=(none|S01|S02|S03|S04|S05|S06|S07|S08|S09|S10)... --staged --unstaged"> $ARGUMENTS </expand>

<objective> *Analyze* the specification of `<getopt-arguments/>` for *potential problems* related to a set of specification quality aspects. </objective>

<flow>

1. <step id="STEP 1: Investigation">

<if condition="<ase-project-boxing/> is equal `black` and <getopt-option-force/> is not equal `true`">

The project source artifacts are classified as a *black box*, so the user does *not* want them inspected or their problems surfaced (the `--force` option lifts this skip). *Skip* the entire investigation and reporting: do *not* invoke any `Bash`, `Glob`, or `Agent` tool and do *not* read any source, only output the following <template/> and then *SKIP* the remaining steps STEP 2 and STEP 3:

<template> <ase-tpl-bullet-normal/> **LINT**: *suppressed* (`project.boxing` is `black`) </template>

</if>

Set <condensed>true</condensed> if <ase-project-boxing/> is equal `grey` and <getopt-option-force/> is not equal `true`, and <condensed>false</condensed> otherwise: a *condensed* report suppresses the full unified diffs of STEP 3.

First, determine the *effective aspect set* <aspects/>, i.e., the specification quality aspects which are checked at all. For this, parse <getopt-option-include/> and <getopt-option-exclude/> as comma-separated token lists, silently dropping the `none` sentinel and any empty token. If a token <token/> is *not* one of the aspect ids `S01`...`S10`, only output the following <template/> and then *STOP* the entire flow (do not perform any further steps):

<template> ⧉ **ASE**: ✪ skill: **ase-spec-lint**, ▶ ERROR: invalid aspect id: **<token/>** </template>

Otherwise set <aspects/> to *all* ten aspect ids `S01`...`S10` if both lists are empty, to the *include* list if only it is non-empty, to all ten *minus* the *exclude* list if only it is non-empty, and to the *include* list *minus* the *exclude* list if both are non-empty. If the resulting <aspects/> is *empty*, only output the following <template/> and then *STOP* the entire flow (do not perform any further steps):

<template> ⧉ **ASE**: ✪ skill: **ase-spec-lint**, ▶ ERROR: options `--include` and `--exclude` cancel out to an empty aspect set </template>

Then split <aspects/> into the *per-file* aspects <file-aspects/> (those of `S01`...`S06`) and the *model-wide* aspects <model-aspects/> (those of `S07`...`S10`), as the latter can be judged on the entire specification model only.

Then, use the following <template/> to give a hint on this step:

<template> <ase-tpl-bullet-secondary/> **LINT INVESTIGATION** </template>

Dispatch the investigation to *sub-agents* via the `Agent` tool so that *no* investigation details leak into the user-visible transcript. The sub-agents perform the silent reading and checking; only their final structured return values are consumed here.

For this, first *silently* resolve the `SPEC` artifacts by calling the `ase_artifact_list(kind: [ "spec" ])` tool of the `ase` MCP server *once* and set <corpus/> to the returned project-relative file list. If <corpus/> is empty, only output the following <template/> and then *STOP* the entire flow (do not perform any further steps):

<template> ⧉ **ASE**: ✪ skill: **ase-spec-lint**, ▶ ERROR: no specification artifacts below `<ase-spec-basedir/>` </template>

<if condition="<getopt-option-staged/> is equal `true` or <getopt-option-unstaged/> is equal `true`">

Then *silently* restrict the linting to the *changed* files of the Git working copy. Set <changes>staged and unstaged</changes> if both <getopt-option-staged/> and <getopt-option-unstaged/> are equal `true`, set <changes>staged</changes> if only <getopt-option-staged/> is equal `true`, and set <changes>unstaged</changes> otherwise. Determine the *repository root* by running the command `git rev-parse --show-toplevel` (taken exactly as given) and capturing its output into <repo-root/>. Then determine the changed files by running the corresponding commands (taken exactly as given), each listing one path relative to <repo-root/> per line, and collect all listed paths, dropping duplicates:

<if condition="<getopt-option-staged/> is equal `true`"> `git -C "<repo-root/>" -c core.quotepath=off diff --cached --name-only --diff-filter=d` </if>

<if condition="<getopt-option-unstaged/> is equal `true`"> `git -C "<repo-root/>" -c core.quotepath=off diff --name-only --diff-filter=d`

`git -C "<repo-root/>" -c core.quotepath=off ls-files --others --exclude-standard` </if>

Keep only those listed paths which are contained