Skip to content

SPEC-001 fails its own validator: a document about writing specs, filed as a spec #475

Description

@explosivebit

Found while implementing #450 (PR #472, merged as 551ddb9). Deliberately not fixed there.

What

forgeplan validate SPEC-001 fails two rules:

x [MUST] spec-summary
x [MUST] spec-contracts

It failed before #472 and still fails after. The other five specs (SPEC-002 … SPEC-006) pass.

Why this is not a validator bug

SPEC-001 is a document about how to write specifications. It has no API contract and no behavioural contract because it does not specify a system — it explains a form. The validator is right to say a spec must contain a contract; SPEC-001 is right to have none. The mismatch is the filing, not the rule.

This was checked before loosening anything. #472 widened spec-contracts to accept behavioural contracts (## Requirements / ## Contract / ## Behavioral Contract) alongside structural ones — SPEC-001 satisfies none of the five, and adding a sixth escape hatch to accommodate one meta-document would be the wrong trade.

Options

  1. Re-file as a Note or a doc under docs/methodology/ and supersede SPEC-001 with a pointer. Cleanest: the content is guidance, and guidance already has a home.
  2. Leave it and accept a permanently red artifact. Costs nothing today, but a validator finding that is understood-and-ignored trains everyone to ignore validator findings.

Option 1 is recommended. Whoever takes it should use supersede, not delete — the content is still useful, only misfiled.

Not urgent

Nothing is blocked by it. Filed because "SPEC-001 fails validation" will otherwise be rediscovered by the next person who runs validate --all and re-derives this reasoning from scratch.

Refs: #450, #472, prob-105

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions