Pular para conteúdo

AUR-001: Inventariar capacidades reais do legado

Documento histórico do board. Pode descrever componentes removidos; para uso atual, consulte o guia do produto.

Behavior

This card records what the base checkout actually contains. It does not claim that the legacy implementation is safe, complete, supported, or suitable for the reconstructed product. It produces a sanitized file inventory and a capability-claim matrix that later cards can characterize, replace, migrate, retain, or delete one owned path at a time.

The inventory contains one lexical row per tracked path outside the card's forbidden namespaces (.git, .env, credentials, secrets, and .board/cards). Each row records only the path, file kind, mode, and a SHA-256 digest. Symlink digests hash the link target text, not the target's contents. No source body, environment value, credential, remote URL, or provider payload is part of this artifact.

Contract

  • .board/research/legacy-files.tsv is a tab-separated snapshot with the exact header path<TAB>type<TAB>mode<TAB>digest.
  • type is file or symlink; regular files use mode 100644 or 100755, and symlinks use 120000.
  • digest is sha256: followed by 64 lowercase hexadecimal characters.
  • Paths are relative, lexical, sorted strictly ascending, and cannot be absolute, traversing, backslash-containing, or control-containing.
  • .board/research/legacy-disposition.md contains the human research table and disjoint machine-readable path pattern -> disposition rules. Every inventory row resolves to exactly one rule. A disposition is a declaration, not permission to alter the named path.
  • tests/specs/AUR-001/claims.yaml maps each semantic implemented claim to an inventory entrypoint and executable inventory test. A disposition record names an observed entrypoint and disposition without asserting capability proof. An absent record must have a non-empty reason and no proof paths.

The inventory row for itself uses the canonical digest of the inventory with its own digest field replaced by 64 zeroes. The acceptance file retains an embedded path list only as a consistency fixture; its digest replaces that fixture with one fixed marker. A pass additionally requires an independent Git index comparison. If that source is unavailable, acceptance is inconclusive rather than green.

Real capability claims

The current snapshot proves focused legacy surfaces, not a complete product:

Surface claim Entrypoint Test Status
Documentation generation cmd/regenerate-docs/main.go not executed by this card disposition: characterize
Language extraction internal/documentation/extractors/registry.go not executed by this card disposition: characterize
Incremental documentation internal/documentation/incremental/manager.go not executed by this card disposition: characterize
Documentation site building internal/documentation/site/runner.go not executed by this card disposition: characterize
Extractor pipeline internal/pipeline/extractor_pipeline.go not executed by this card disposition: characterize
LLM orchestration internal/llm/orchestrator.go not executed by this card disposition: characterize
OpenAI provider adapter internal/llm/provider/openai/openai.go not executed by this card disposition: characterize
Shared provider types pkg/types/providers.go no semantic proof in this card disposition: characterize
Public action runtime absent absent disposition: absent

This card does not promote file existence into a capability assertion. Only an implemented claim with a real executable test is semantic proof; disposition records preserve observed legacy surfaces for later characterization. The acceptance command does not execute legacy files.

Limits and security

The acceptance program is a linter over bounded metadata. It refuses malformed rows, duplicate paths, non-lexical order, unsafe paths, unsupported file kinds, more than 10,000 rows, or an inventory larger than 64 MiB. It also refuses unmatched, multiply matched, stale, and absent disposition rules, and claims without real proof paths. A missing host utility or unavailable container is infrastructure/inconclusive, never behavioral RED or GREEN.

The ten named legacy surfaces in the acceptance program are anti-shortcut anchors: they ensure that the independently derived inventory describes real legacy areas rather than an empty or truncated list. No legacy command is run, no network request is made, and the configured secret canary must not occur in output or artifacts.

Example

$ bash tests/acceptance/AUR-001.sh
{"card":"AUR-001","scenario":"AC-001","result":"pass"}
$ echo $?
0

The output is an observation only. It is not a board transition, approval, or evidence bundle. A missing inventory is a typed unmapped-tracked-file failure; a missing host tool or unavailable acceptance engine is reported as infrastructure/inconclusive.

Diagnostic procedure

  1. Run bash -n tests/acceptance/AUR-001.sh.
  2. Run bash tests/acceptance/AUR-001.sh from the repository root and preserve its exit code without a pipe.
  3. For unmapped-tracked-file or stale-path, compare the inventory against the independent Git tracked-path set and check lexical ordering and the exact disposition rules.
  4. For claim-without-proof, claims-manifest-invalid, or absent-without-reason, repair only tests/specs/AUR-001/claims.yaml with semantic proof or an explicit disposition/reason.
  5. Run go run tests/integration/AUR-001.go for the independent reader. It checks the same metadata from a separate implementation and never runs a legacy capability.