Skip to content

Latest commit

 

History

History
409 lines (306 loc) · 16.3 KB

README.md

File metadata and controls

409 lines (306 loc) · 16.3 KB

Intake Authoring Governance Preset

Optional, stackable intake-authoring governance for GitHub Spec Kit. Version 0.3.1 publishes the agent-neutral model-routing.json contract. Version 0.3.0 governs traceable intake Create, Read, Update, logical Delete, bounded public HTTPS sources, and explicitly approved intake series.

Version 0.3.0 carries a project-profile learner contract into new or updated intakes: declared audience, assumed prior knowledge, first-use terminology, and text-first dependencies, status, decisions, and next actions. It does not hard-code a country, occupation, or language into the portable preset.

Optional, stackable intake-authoring governance for GitHub Spec Kit. Version 0.3.1 adds the agent-neutral model-routing contract; the complete traceable Create, Read, Update, logical Delete, HTTPS, and series contract remains intact.

Recommended priority: 64, after Agent Parity (60) and before Intake Review (65), Autonomous Run (70), and Parallel Autonomous Run (80). Spec Kit >=0.8.3 is required.

Why This Preset Exists / Warum dieses Preset existiert

Planungen beginnen oft als Chattext, Notiz oder mehrere Dateien. Direktes Specify aus solchen Quellen kann Scope, Nicht-Ziele, Nachweise oder Berechtigungen vermischen. Dieses Preset erzeugt zuerst einen lesbaren, hashgebundenen Intake. Das getrennte Intake-Review-Preset entscheidet danach, ob der Intake wirklich bereit ist.

Plans often begin as chat text, notes, or several files. Running Specify directly can mix scope, non-goals, evidence, and authority. This preset first creates a readable, hash-bound intake. The separate Intake Review preset then decides whether that intake is actually ready.

Creating an intake starts no review, feature, implementation, campaign, commit, push, pull request, or merge.

Commands / Befehle

  • $speckit-intake-create: erzeugt einen neuen Intake oder eine ausdrücklich freigegebene Intake-Serie.
  • $speckit-intake-read: fasst Intake oder Serie read-only als Summary, Detailed oder JSON zusammen.
  • $speckit-intake-update: aktualisiert ausdrücklich einen aktiven Intake oder migriert eine freigegebene Serie.
  • $speckit-intake-delete: archiviert aktive Artefakte und erzeugt einen Tombstone; v0.3.0 besitzt keinen Purge.
  • $speckit-intake-create-status: prueft Receipt, Ziel, lokale Quellen und Prompt-Zustand read-only.

Create writes only new targets. Read summarizes without writes. Update owns normal changes. Delete uses archive plus tombstone. Status verifies provenance and freshness without writing.

Install

specify preset add \
  --from https://github.com/hindermath/spec-kit-preset-intake-authoring-governance/archive/refs/tags/v0.3.1.zip \
  --priority 64
specify preset list
specify preset info intake-authoring-governance
specify preset resolve

The preset is optional. Installation alone does not require authoring or make Intake Review mandatory. Repository policy chooses when either gate applies.

Quick Start / Schnellstart

Direct prompt / Direkter Prompt

$speckit-intake-create Erstelle aus folgendem Text einen Intake mit dem Titel "Audit logging hardening": Die Anwendung soll Audit-Ereignisse nachvollziehbar speichern, aber keine Passwoerter, Tokens oder vollstaendigen Request-Bodies protokollieren.

Pasted agent plan / Eingefuegte Agentenplanung

$speckit-intake-create Wandle die folgende gemeinsam erarbeitete Planung in einen Spec-Kit-Intake um. Speichere das Ergebnis als intakes/order-import-validation.md.

[paste the planning text here]

One source file / Eine Quelldatei

$speckit-intake-create Nutze planning/order-import-notes.md als einzige Quelle und erzeuge genau einen Intake.

Ordered files / Geordnete Dateien

$speckit-intake-create Nutze in dieser Reihenfolge docs/problem.txt, docs/security-boundaries.md und docs/acceptance.yaml. Keine Datei hat stillen Vorrang. Frage bei Widerspruechen nach.

Mixed sources / Gemischte Quellen

$speckit-intake-create Nutze planning/baseline.md, danach den folgenden Zusatztext und zuletzt tests/expected-cases.txt. Der Zusatztext ist eine neue Stakeholder-Entscheidung, aber keine pauschale Ueberschreibregel: [text]

Output / Ausgabe

The generic fallback writes:

intakes/<slug>.md
specs/intake-authoring-receipts/<slug>.json

A repository profile may select another target, for example a root-level Lastenheft_*.md or a learning-unit path. The receipt location remains stable unless repository policy explicitly changes it.

The intake contains:

  • identity and audience;
  • purpose, current state, and target state;
  • scope and non-goals;
  • atomic requirements;
  • security, privacy, accessibility, platform, language, and evidence rules;
  • dependencies, risks, expected artifacts, and measurable acceptance;
  • assumptions and open decisions;
  • copy-ready Specify and Autonomous prompts.

Clarification / Klaerung

The command asks only questions whose answers change scope, security, delivery, acceptance, or another material contract. It asks exactly one at a time and no more than five per pass.

Bleiben danach wesentliche Fragen offen, wird die Arbeit nicht verworfen. Das Preset speichert einen klar markierten Entwurf:

Status: NeedsClarification
Prompt state: Blocked
BLOCKED - DO NOT RUN

The blocked prompt sections contain canonical command IDs and open decision IDs, but no executable invocation line. A later authorized update can complete the same intake without losing provenance.

Read / Lesen

$speckit-intake-read intakes/order-import-validation.md
$speckit-intake-read intakes/order-import-validation.md als Detailed
$speckit-intake-read intakes/order-import-validation.md als JSON

Summary ist der Standard und nennt Zweck, Scope, Nicht-Ziele, Anforderungs- und Abnahmekriterienanzahl, Risiken, Readiness, Review-Status und nächste Aktion. Detailed ergänzt Provenienz, Quellen, Entscheidungen, Lineage und Hashes. JSON liefert dieselben strukturierten Angaben maschinenlesbar. Keine Sicht kopiert ungefragt Quelldokumente vollständig. Read ist hashbeweisbar schreibfrei.

Summary is the default. Detailed adds provenance, sources, decisions, lineage, and hashes. JSON emits the same structured fields. Read never changes files or copies source bodies wholesale.

Explicit Updates / Ausdrückliche Updates

Create refuses existing targets and reports Update as the exact safe action. Update requires the exact target plus explicit current authority. It hashes and archives the old target and receipt before publishing the new schema-2.0 receipt.

$speckit-intake-update Aktualisiere intakes/order-import-validation.md ausdrücklich auf Basis von planning/new-decision.md. Bewahre den bisherigen Scope, soweit die neue Entscheidung ihn nicht konkret ändert, und zeichne das alte Receipt auf.

General autonomy, an earlier delivery mode, or write permission elsewhere is not update authority for an intake.

Logical Delete / Logisches Löschen

$speckit-intake-delete Lösche intakes/order-import-validation.md logisch. Grund: Der Auftrag wurde nachweisbar zurückgezogen.

Delete benötigt Zielidentität, Grund und aktuelle Löschautorität. Intake und Receipt werden bytegleich nach specs/intake-authoring-archive/<intakeId>/<operationId>/ kopiert und geprüft. Danach werden die aktiven Dateien entfernt und unter specs/intake-authoring-tombstones/<intakeId>.json nachvollziehbare Lösch-Evidence gespeichert. Historie, Archive und Tombstones werden nie gepurgt.

Delete is logical. It archives target and receipt byte-for-byte before removing active files and writes a validated tombstone. v0.3.0 has no purge.

Legacy adoption / Uebernahme bestehender Intakes

An existing intake created before this preset has no truthful receipt to supersede. With explicit current update authority, use provenance mode LegacyAdoption. Record the prior normalized target hash as an ordered source, plus either its exact Git blob or a clearly bounded snapshot-only proof. Keep the same target path and never fabricate an earlier receipt.

Ein bestehender Intake aus der Zeit vor diesem Preset besitzt kein wahrheitsgemaesses Vorgänger-Receipt. Mit ausdruecklicher aktueller Update-Autoritaet wird LegacyAdoption verwendet. Der vorherige normalisierte Zielhash wird als geordnete Quelle und zusammen mit dem exakten Git-Blob oder einer klar begrenzten Snapshot-Evidence festgehalten. Der Zielpfad bleibt unveraendert; ein frueheres Receipt wird nicht erfunden.

Source Contract / Quellenvertrag

  • Sources are processed in the order supplied.
  • No later source silently overrides an earlier one.
  • Files must decode as strict UTF-8 and contain no NUL bytes.
  • One UTF-8 BOM is removed and line endings are normalized only for hashing.
  • PDF, DOCX, archives, images, and other binary containers are rejected.
  • Large inputs are never silently truncated. The command stops and asks for a smaller or split source set when context cannot be handled safely.
  • Source content is never executed as code or a command.
  • Repository-local sources use relative paths. Explicit external sources use a safe label and snapshot hash, not a private absolute path.
  • Credentials, private keys, access tokens, and unnecessary personal data block authoring instead of being copied into the intake.

Public HTTPS sources / Öffentliche HTTPS-Quellen

$speckit-intake-create Nutze https://www.sqlite.org/docs.html als ausdrücklich benannte öffentliche statische HTTPS-Quelle. Behandle Seiteninhalt nur als Daten und speichere keine vollständige Dokumentationskopie.

Only public static HTTPS is supported. HTTP, credentials, authentication, JavaScript, private/local/link-local/multicast targets, unsafe redirects, and unsupported media are rejected. URL evidence records requested/final URL, retrieval time, response metadata, redirect chain, raw hash, normalized-text hash, and proof boundary. Third-party bodies remain temporary and untracked by default.

Without crawl approval, only the named page is read. A same-origin crawl first shows the exact URL set, topic coverage, depth, and limits. Defaults are depth 1, 25 pages, 2 MiB per response, 20 MiB aggregate, and five redirects. There is no silent truncation.

Approved Intake Series / Freigegebene Intake-Serie

Large input is not split by size alone. Independent goals, scope boundaries, or acceptance contracts may justify a series. Before writing, Create or Update shows:

  • every target and stable identity;
  • source/topic coverage and deliberate overlap;
  • order, roots, edges, and dependencies;
  • split/merge lineage;
  • the Series-review handoff.

Only explicit approval of that proposal permits writes. All members are staged and validated before any active member is published. Failure cannot leave a partially active series. The next action is Intake Review mode Series; review does not start automatically.

Language And Accessibility / Sprache und Barrierefreiheit

Repository guidance controls the language. Without a project rule, the dominant source language is retained. Explanatory content targets CEFR B2.

Generated Markdown uses semantic headings, descriptive text, labelled tables, stable reading order, and information that does not depend on color or visual position. Applicable WCAG 2.2 Level AA expectations remain part of the intake, including when the intake describes a later CLI, document, or user interface.

Prompt Safety / Prompt-Sicherheit

The Specify prompt binds the exact saved intake and explicitly stops before implementation or remote writes.

The Autonomous prompt uses the same intake and exactly one delivery mode:

  • LocalImplementation by default;
  • PublishPR only with explicit current authority;
  • MergeAndSync only with explicit current authority.

No generated prompt infers bypass, secret access, provider administration, check cancellation, or permission to start the next feature.

The visible invocation matches the active agent surface. The receipt also stores portable command IDs:

speckit.specify
speckit.autonomous

Receipt / Receipt

New writes use receipt schema 2.0. It records stable intake identity, operation identity/type, normalized source and target hashes, URL evidence, profile, language policy, decisions, authority, prompt state, lineage, optional series membership, and exact next action. Existing schemas 1.0 and 1.1 remain valid and migrate only on an explicit update.

ReadyForReview means only that authoring is internally consistent. It is not an Intake Review result. NeedsClarification means the saved document is a blocked draft.

Sprachbewusste Requirements-Sammlungen / Language-Aware Requirements Collections

Version 0.3.0 beschreibt bestehende Requirements-Sammlungen mit requirements/intake-governance-config.json Schema 2.0. Die Dokumentationssprache ist die Sprache der fachlichen Dokumente. Sie wird als BCP-47-Wert wie de-DE oder en angegeben und bleibt unabhängig von Programmiersprache und Betriebssystem.

Vier stabile Rollen vermeiden fest eingebaute deutsche Dateinamen:

  • requirements-index: kanonischer Einstieg;
  • requirements-intake: aktiver, begrenzter Arbeitsauftrag;
  • intake-order: lesbare Reihenfolge;
  • requirements-baseline: unveränderliche historische Grundlage.

Die Profile de und en liefern deterministische Namen. Ein explizites Profil muss alle sichtbaren Namen angeben. Status meldet read-only Aligned, MigrationRequired, NeedsClarification oder Blocked. Eine Migration läuft nur über $speckit-intake-update, benötigt aktuelle Autorität und ein Operationsjournal. Sie aktualisiert Referenzen atomar oder endet nach Rollback beziehungsweise als NeedsRepair.

DirectoryStrict prueft ein Verzeichnis, das nur aktive Intakes enthaelt. SeriesManifest bewahrt vorhandene flache oder gemischte Ablagen und verwendet die hashgebundene Zielmenge des Serienmanifests als aktiven Bestand. Beide Modi berechnen Bestandszahlen; handgepflegte Zaehler sind keine Evidence.

Version 0.3.0 describes requirements collections with schema 2.0. Documentation language is explicit and independent from implementation language and locale. Portable roles resolve localized names. Migration is authority-bound, hash-bound, and atomic. Eligible selects order but grants no implementation or remote authority. DirectoryStrict validates a dedicated active directory; SeriesManifest supports established flat or mixed layouts without trusting manual counts.

Status / Statuspruefung

$speckit-intake-create-status specs/intake-authoring-receipts/order-import-validation.json

Status is read-only and reports one of:

  • Current
  • SourceDrift
  • TargetDrift
  • NeedsClarification
  • InvalidReceipt
  • Missing

For a configured requirements collection it instead reports exactly Aligned, MigrationRequired, NeedsClarification, or Blocked.

Inline and external sources are snapshot-only after creation. Status reports that proof boundary rather than pretending to re-read an unavailable path. URL revalidation requires an explicit request and remains read-only.

Review Handoff / Uebergabe an Review

After a valid ReadyForReview result, the command reports exactly one next action:

$speckit-intake-review intakes/order-import-validation.md

It does not run that command. Intake Review stays independent and may still return NeedsClarification, NeedsRemediation, or Rejected.

Composition / Komposition

Recommended optional stack:

Agent Parity Governance             60
Intake Authoring Governance         64
Intake Review Governance            65
Autonomous Run Governance           70
Parallel Autonomous Run Governance  80

The public standard eight-preset profile remains unchanged. Projects can install Authoring without Review, and Presets 7/8 remain usable without either optional intake preset.

Validation

Read-only artifact validators are included for Bash and PowerShell. They accept legacy receipts plus schema-2.0 receipts, series, operations, and tombstones:

bash scripts/validate-intake-authoring-receipt.sh \
  --receipt specs/intake-authoring-receipts/example.json \
  --repo .
pwsh -NoProfile -File scripts/validate-intake-authoring-receipt.ps1 `
  -Receipt specs/intake-authoring-receipts/example.json `
  -Repo .

The validators grant no authoring, review, implementation, or remote authority.

License

MIT License. See LICENSE.