trueline 0.1.0.dev0__tar.gz

trueline-0.1.0.dev0/.gitignore

@@ -0,0 +1,15 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+
+# Ambientes e builds
+.venv/
+dist/
+build/
+
+# Caches de ferramentas
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/

trueline-0.1.0.dev0/.gitlab-ci.yml

@@ -0,0 +1,38 @@
+# You can override the included template(s) by including variable overrides
+# SAST customization: https://docs.gitlab.com/user/application_security/sast/#available-cicd-variables
+# Secret Detection customization: https://docs.gitlab.com/user/application_security/secret_detection/pipeline/configure/
+# Dependency Scanning customization: https://docs.gitlab.com/user/application_security/dependency_scanning/dependency_scanning_sbom/#customizing-analyzer-behavior
+# Container Scanning customization: https://docs.gitlab.com/user/application_security/container_scanning/#customizing-analyzer-behavior
+# Note that environment variables can be set in several places
+# See https://docs.gitlab.com/ci/variables/#cicd-variable-precedence
+stages:
+- test
+- secret-detection
+sast:
+  stage: test
+include:
+- template: Security/SAST.gitlab-ci.yml
+- template: Security/Secret-Detection.gitlab-ci.yml
+variables:
+  SECRET_DETECTION_ENABLED: 'true'
+secret_detection:
+  stage: secret-detection
+lint-test:
+  stage: test
+  image: ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+  variables:
+    UV_CACHE_DIR: .uv-cache
+  cache:
+    key:
+      files: [uv.lock]
+    paths: [.uv-cache]
+  before_script:
+    # The slim uv image ships neither git (the test suite spawns real `git`
+    # subprocesses) nor libatomic.so.1 (pyright-python's bundled Node needs it).
+    - apt-get update && apt-get install -y --no-install-recommends git libatomic1
+  script:
+    - uv sync --locked
+    - uv run ruff check .
+    - uv run ruff format --check .
+    - uv run pyright
+    - uv run pytest

trueline-0.1.0.dev0/.python-version

@@ -0,0 +1 @@
+3.12

trueline-0.1.0.dev0/CLAUDE.md

@@ -0,0 +1,220 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+`trueline` is a **Spec-Driven Development (SDD) framework for Claude Code users**: specs and
+architecture are living documents and the source of truth; code is regenerable output. It is a Python
+CLI (`trueline`) over a **headless core** (files + derived state + a deterministic CLI) that an
+**external orchestrator** drives phase-by-phase, invoking the project's own Claude Code headless.
+
+This is its **own independent git repo** (no remote yet — work on `main`). It lives inside the
+`dsb-ai-flow` VS Code workspace alongside four sibling SDD projects — `../OpenSpec/`, `../spec-kit/`,
+`../agentspec/`, `../everything-claude-code/` — which are **used as reference** (trueline steals the
+spec fold from OpenSpec, the constitution/clarify/templates from spec-kit, the PRP/build-loop/drift
+validators from ECC). When grounding a design decision, read the relevant sibling's real code.
+
+## `docs/` is the source of truth — read it first
+
+The methodology and the entire multi-milestone plan live in `docs/`, in a strict authority order:
+
+- **`STATE.md`** — the **consolidated project-state snapshot** (what/where/how/what-remains). Start
+  here for quick orientation; the docs below remain the source of truth for details.
+- **`DESIGN.md`** — the conceptual design (v5), the **top authority**. On any conflict, the design wins.
+- **`M1-SPEC.md`, `M2-SPEC.md`, `M3-SPEC.md`, `M4-SPEC.md`** — the technical *what*, decided
+  section-by-section. The source of truth for the implementation. Errata are recorded in the doc
+  headers, never by a general re-review. (`M4-SPEC.md` is COMPLETE + **FINAL (r7)** — seven
+  adversarial review rounds, stamps in its header.)
+- **`M4-HANDOFF.md`** — the **single current handoff** (start here): M4 is **IMPLEMENTED** and
+  green, and **`M4-E2E-PLAN.md` is authored + APPROVED (2026-07-10, pre-execution)**; the next
+  sessions **execute the M4 E2E, one phase per session** (session 1 = guinea-pig selection
+  against the plan's §1 profile + preflight + Phase A), each session closing by updating the
+  plan's §8 record, the handoff and the kickoff. Supersedes `M3-FOLLOWUP-HANDOFF.md` +
+  `M3-HANDOFF.md` (both historical). The M3 calibration/errata/governance outcomes live in
+  `M3-E2E-PLAN.md` §8.
+- **`M2-IMPL-PLAN.md` / `M2-ASSETS.md` / `*-E2E-PLAN.md`** — the *how* (per-step mini-designs), the
+  drafted assets, and the end-to-end validation records. `PROMPT-NEXT-SESSION.md` is the kickoff prompt.
+
+**Current state:** M1 (skeleton), M2 (governance), M3 (the full loop) and **M4 (Brownfield) are
+implemented AND E2E-validated.** M1/M2/M3 were E2E-validated with a real model and calibrated (the
+M3 multi-stack E2E: 9/9 criteria; record in `M3-E2E-PLAN.md` §8). **M4 is now E2E-validated too
+(2026-07-11): the four-session brownfield E2E closed with all eleven §6 criteria met — B2/B3 earn
+promotion to HIGH; the "Is not" mechanical escalation is NOT ratified** (record + verdict in
+`M4-E2E-PLAN.md` §8). **Publication (remote/CI/PyPI) is now UN-DEFERRED** (the M1/M2/M3 gate is
+satisfied). The impl-plan's four steps all landed on `main` (steps 1 → 2 → 3 → 4a…4e, 19
+commits `8952fab → 235282e`), the tree is clean, and CI is green — **875 tests** (872 through the
+three reviews; **+3 with the M4-E2E Phase-B pre-run fix `e2edb24`** — the missing
+`src/trueline/__main__.py`), ruff clean, ruff-format clean, **pyright strict 0 errors** (the M1–M3
+baseline was 561; 790 at the end of implementation, 804 after the M4-only review, 831 after the
+second review). A **post-implementation review** (2026-07-09,
+`4d714e0 → e2e06e4`) audited the whole milestone (8 parallel auditors, each finding verified
+against the code): completeness came back with **zero gaps**, and 6 real findings + a robustness
+follow-up batch were fixed, each with tests. It ratified **three pointed errata — E1/E2/E3** — in
+the `M4-SPEC.md`/`M4-IMPL-PLAN.md` headers (§2.5 assemble rebuild trigger; §4 item-7 dead-round
+suite; §5 flip ordering); **no decision reversed**. A **second, whole-project review** (2026-07-09,
+`d8e4d20 → 2a3a6b9`) then audited M1→M4 (12 parallel readers, each finding re-verified against the
+code; two proposed schema-hardening items rejected for contradicting the layer design): **4 HIGH +
+a batch of MEDIUM/LOW** fixed, each with a test — ratifying **`M4-SPEC.md` E4** (plan.md ADR
+`scope:`) + the **E2 completion** (the dead-round-suite walk) and **`M3-SPEC.md` M3-a/M3-b**
+(qualified `FULFILLS`; the single-per-line `MIRROR` example). A **third, fresh-eyes review**
+(2026-07-09→10, `fce58e7 → 10fd659`, 11 readers told NOT to trust the prior fixes) then caught
+real defects the two prior passes missed — chiefly a **systemic exit-code-contract hole**
+(framework errors escaping to exit 1) — and, on fresh scrutiny, **fixed two items the second
+review had accepted** (the heading-slug collision; config-encoding/resume): **8 clear bugs + 3
+judgment calls + a 6-item LOW tail**, each with a test, ratifying a **`M4-SPEC.md §4` clarifying
+errata** (validate runs the completion battery report-only) + the **E4 extension**
+(`architecture-setup.md` scope gap). The full ledger + the accepted non-issues + the one deferred
+follow-up (GOV-3: an atomic/resumable `init`) are in **`docs/PROJECT-REVIEW.md`**. The three M4 authoring docs are converged and closed:
+**`M4-SPEC.md` FINAL (r7)** (12 sections, seven adversarial review rounds), **`M4-IMPL-PLAN.md`
+COMPLETE, review CLOSED** (three rounds, ten passes), **`M4-ASSETS.md` COMPLETE (15/15), review
+CLOSED and converged** (two rounds, eight passes) — never re-review them as a sweep; a real
+defect becomes a pointed ratified erratum in the doc header. The M4 code lives across
+`src/trueline/adoption/`, `src/trueline/gitio.py`, `src/trueline/cli/adopt_*.py`, and the new
+checks/roles/assets. **`M4-E2E-PLAN.md` is authored and APPROVED (2026-07-10,
+pre-execution)** — brainstormed decision by decision on the `M3-E2E-PLAN.md` mold: the
+guinea-pig **selection profile** (§1 — a real, pre-existing multi-stack repo; no repo selected
+yet), the harness split (FIFO+pump for `init`; a **real terminal** for `approve`'s TTY-checked
+walk), Phases A–D + staged episodes + 10 extras, eleven success criteria and the two gated
+decisions (B2/B3 promotion; the "Is not" escalation). The run executes **one phase per
+session** (a user decision): each session closes by updating the plan's §8 record,
+`M4-HANDOFF.md` and `PROMPT-NEXT-SESSION.md`. **Sessions 1 & 2 are DONE (2026-07-10):** per the §1
+amendment the guinea pig is **purpose-built in-workspace** — `cobaia-brownfield/` ("linkstash":
+FastAPI+SQLite `api` w/ a green pytest suite + TS/Node `cli` w/ no unit tests, over an HTTP `/api`
+seam). Session 1: preflight + Phase A (brownfield `init` + two locals + three A-era extras;
+charter 3 "Is not" bullets, #1 contradictable; global constitution's cross-part "Contract-only
+seam" MUST). **Session 2: Phase B — the RE fan-out ran green** (scan → describe/validate with the
+`cli` `did-not-run` demotion → capability-plan pause → assemble: 7 clean specs + 9 scoped ADRs +
+B1 green → hotfix-sync staleness biting only app-core → §2.5 plan reconcile → E1 selective
+re-assemble → 5 B-era extras). **One pre-run code fix (`e2edb24`, user-approved):** a missing
+`src/trueline/__main__.py` blocked `adopt run`'s subprocess spawn (CI missed it — `_spawn` is
+monkeypatched); **CI now 875 tests**, recorded in `PROJECT-REVIEW.md` (fifth finding). **Session 3:
+Phase C — the completion gate ran green end-to-end (2026-07-10→11):** the dead round (excluded-file
+commit → the api suite round dies, no module stale) → `status` pre-gate → the non-TTY `approve`
+refusal (exit 2) → **`approve` #1** over a **pexpect pty** (the walk + the deliberate
+decline→exit 2→resume-without-re-ask + a 5-finding skeptic → approval #1) → **the reopen cycle**
+(3 constraint kinds on api/app-core + the E1 re-partition rider → **selective re-assemble: 3 rebuilt
+/ 4 byte-identical**; the corpus-wide guard fired on a real code bug — `evidence_file` doesn't
+recognize a line-RANGE EVIDENCE anchor — re-steered to single-line citation) → **`approve` #2**
+(only the 5 changed identities re-asked; the three kinds resolving by their three paths; skeptic
+re-sampled, 7 findings → approval #2) → **`flip`** (record-first → `governed`) → the **`--no-ff`
+cutover** into `main` (`trueline validate` exit 0, both suites green, `status` sane). Every step
+exit 0, all sonnet. **Session 4: Phase D — the post-flip measurement protocol ran green end-to-end
+(2026-07-11):** D-1 arch-review (advisory, exit 0, 2 SUGGESTIONs) → **D-2** the clean seam-crossing
+change `add-link-note` (FULL cycle to merge `ec6c3f6`: multi-layer conformance silent, **B2/B3
+silent-on-clean**, seam extract consumed, qualified FULFILLS, **multi-file finalize candidate**
+judged, **traceability index frozen**, both suites green) → **D-3 B2 fired + silent-after-correction**
+→ **D-4 B3 fired + silent-after-correction + the decompose-judge weak-package healing loop** → **D-5
+"Is not"** (`charter-is-not` HIGH, full per-bullet verbatim enumeration, operator refuse → **exit 2**)
+→ the two post-flip extras (impossible-state CRITICAL exit 1; post-flip refusal exit 1). **VERDICT:
+M4 brownfield path VALIDATED — all eleven §6 criteria met; B2/B3 earn HIGH; the "Is not" escalation
+NOT ratified; GOV-3 did not bite** (`M4-E2E-PLAN.md` §8). **The post-verdict follow-up session
+(2026-07-13, commits `8cb5e1c → bbc0d17`) cleared the four concrete items on `main` — CI green,
+now 879 tests, pyright strict 0:** the ratified `evidence_file` line-range fix (+ regression tests),
+the B2/B3 WARNING→HIGH promotion (+ the §7.2 injection-test fixes), the real-I/O-boundary test guards
+(the `python -m trueline` subprocess + the anchor grammar), and the §8 calibrations
+(`describer`/`adr-deriver`/`constitution` assets + the conformance-criterion stdout + the `validate`
+demoted-echo). **The four designed technical follow-ups then landed on `main` (2026-07-13, in order
+1 → 4 → 2 → 3, each green): item 1 `c962a31` (conformance `is_not_walk` — the auditable "Is not"
+walk), item 4 `757527a` (configurable `runtime.model`/`runtime.effort` + per-command
+`--model`/`--effort`), item 2 `e418ce8` (in-walk bulk dispositions in `adopt approve`), item 3
+`257b75d` (resumable/derived `init` — GOV-3); designs + implementation-time deviations in
+`docs/POST-M4-DESIGN.md`. CI now 928 tests, pyright strict 0, ruff/format clean.** **Remaining:**
+only **publication (remote/CI/PyPI), un-deferred and the operator's call** (`docs/M4-HANDOFF.md` §2;
+`docs/PROJECT-REVIEW.md`) — the `is_not_checked` nicety / item-5 pendency-walk / item-6 GOV-3 are
+now CLOSED (they were the designed items 1/2/3).
+
+## Commands
+
+The toolchain is **`uv`** (see `.python-version`, `uv.lock`). CI (`.github/workflows/ci.yml`) runs
+exactly these four, in order — run them before considering work done:
+
+```bash
+uv sync --locked            # install (dev group included)
+uv run ruff check .         # lint
+uv run ruff format --check . # format check (use `uv run ruff format .` to fix)
+uv run pyright              # STRICT type check — zero errors is the standing bar
+uv run pytest              # full suite (testpaths=tests, -q --strict-markers)
+
+uv run pytest tests/fold/test_apply.py            # a single file
+uv run pytest tests/fold/test_apply.py -k <name>  # a single test
+uv run trueline --help     # the CLI surface
+uv build                   # wheel/sdist (assets in src/trueline/assets/ ship automatically)
+```
+
+`pyright` is configured **strict** and points at the local `.venv` — private cross-module use (a
+leading `_`) is rejected, which is why some helpers are deliberately de-underscored.
+
+## Architecture (the big picture)
+
+The seven phases — `propose → clarify → plan → decompose → build → validate → finalize` (+ the
+`approve`/`reject` human gate, plus `init`/`status`/`adr`) — are wired in `cli/__init__.py`. Each phase
+maps to a package under `src/trueline/`:
+
+| Package | Role |
+|---|---|
+| `schemas/` | Strict pydantic models for every artifact (config, change, ADR, findings, verdicts) + the normative `heading_slug`. |
+| `fold/` | Spec-delta parser/validator/applier — a **faithful port of OpenSpec's deterministic fold** (parity-tested). This is the *only* mechanical fold; architecture never folds. |
+| `adr/` | ADR parse + **projected state** (`project`) + log invariants + cross-refs. **ADR identity = slug** (merge-safe, no sequential number). |
+| `state/` | **Derived state machine**: `inventory` reads the filesystem, `derive` projects it into a phase. State is *never stored* — it comes from which artifacts exist. |
+| `checks/` + `gates/` | A **single check registry** (`checks/battery.py`) consumed by gates, `validate`, and `status`; a **cumulative gate table** (`gates/table.py`) — the gate of phase N re-runs all prior phases' checks (this is what makes drift-detection "pull"). |
+| `judge/` | The **judge-until-convergence loop** (≤5 rounds) for finalization: monotonic candidate generation, atomic write, escalation. |
+| `invoke/` | Headless invocation — `sdk`/`cli` drivers, per-role tool `policy`, one-shot + multi-turn `interactive`. |
+| `cli/` | Typer commands + the **real** synthesizer/judge/scanner adapters (`cli/roles.py`). |
+| `assets/` | Templates, instructions, hooks, CI, taxonomy — the **phase intelligence**, embedded in the package. |
+
+### Cross-cutting patterns (know these before touching anything)
+
+- **Pure core, shell with I/O.** Checks and derivation operate over **preloaded facts**
+  (`CheckContext`, `ChangeInventory`) and are pure; only the executor/CLI reads disk. The paired
+  functions signal it: `derive_state(inventory)` (pure) vs `derive_state_at(path)` (I/O shell).
+  Add logic in the pure layer, wire I/O at the edge.
+
+- **State is derived, not stored.** `state/derive.py` infers the phase from artifacts on disk;
+  finalization's sub-state (`loop-in-progress`, `awaiting-approval`, `escalated`, `ready-to-write`,
+  `returned-from-rejection`) is materialized as files under `evidence/finalize/` so it survives a
+  crash. `change.yaml` deliberately does **not** store phase state.
+
+- **Two layers, fail-closed vs advisory.** Every check is **layer A** (mechanical, fail-closed) or
+  **layer B** (semantic, advisory + human gate). `gates.blocking_severity` governs only layer A;
+  layer B is always advisory regardless of severity.
+
+- **Roles are injected interfaces.** The judge loop (`judge/loop.py`) takes `Synthesizer`/`Judge`
+  Protocols — **test doubles in tests, real adapters in `cli/roles.py`**. Context between roles passes
+  through **workspace files, never conversation history** (design principle P6: don't overload context).
+  A judge verdict must echo the candidate's `generation`/`round` to be accepted.
+
+- **Exit codes are a contract** (`cli/output.py`): `0` ok · `1` blocked by layer A · `2` human
+  declined at layer B · `3` framework error. Most commands support `--json`.
+
+- **Two living baselines evolve differently.** Spec = discrete requirements → mechanical fold.
+  Architecture = a graph of ADRs → **semantic re-synthesis** via the judge loop, never a fold.
+
+## Working style (the user has strong, documented preferences — see M2-HANDOFF §9)
+
+- **Design/spec phases are Socratic brainstorm:** one decision at a time — lay out options with
+  trade-offs, **recommend one, confirm before writing** it into the doc. Keep a running "decided so
+  far". The user refines recommendations often (expected). Communicate in **clear, didactic
+  Portuguese**; explain each point self-sufficiently (don't reference decisions by code/number).
+- **Ground in real code before recommending** — read the M1/M2 implementation and how the siblings
+  solve the same phase; launch exploration subagents in parallel; verify factual premises.
+- **Simplicity bias (P6):** before proposing new machinery, ask *"does a mechanism we already have
+  solve this?"* — phase intelligence arrives as better templates and new checks on the **same
+  skeleton**, not new machinery.
+- **Implementation phases invert this:** follow the closed docs, consult only on a genuine gap. Keep
+  `pyright` strict + `ruff` clean from the first commit; write tests alongside each step; small commits
+  (English, on `main`), and report results faithfully (failed = show the output).
+
+## Do not
+
+- **Don't re-review the converged docs** (`DESIGN`/`M1-SPEC`/`M2-SPEC`/…). A real defect becomes a
+  pointed, ratified erratum in the doc header — never a general audit sweep.
+- **Don't hand-edit** `tests/fold/parity/fixtures.json` (regenerate via `tests/fold/parity/generate_fixtures.mts`
+  against a real OpenSpec checkout) or anything under `evidence/finalize/` (use the operations in
+  `judge/workspace.py`).
+- **Don't edit `plugin/`-style generated output**: the assets that ship in the wheel are the sources
+  under `src/trueline/assets/` (they ship via hatchling's default inclusion — `force-include` breaks
+  the build because the assets live inside the package).
+- **Publishing (GitHub remote, CI secrets, PyPI) is UN-DEFERRED** as of the M4 Phase-D verdict
+  (2026-07-11 — M4 = implementation + E2E validated). It's no longer off-limits to propose; the
+  operator decides whether/when (don't push it unasked).

trueline-0.1.0.dev0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luis Muller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

trueline-0.1.0.dev0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: trueline
+Version: 0.1.0.dev0
+Summary: Spec-Driven Development (SDD) framework for Claude Code users.
+Project-URL: Homepage, https://gitlab.com/simple-tools1/trueline
+Project-URL: Repository, https://gitlab.com/simple-tools1/trueline
+Author: Luis Muller
+License-Expression: MIT
+License-File: LICENSE
+License-File: THIRD-PARTY-NOTICES.md
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.12
+Requires-Dist: claude-agent-sdk>=0.2.98
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.24
+Description-Content-Type: text/markdown
+
+# trueline
+
+**Spec-Driven Development (SDD) framework for Claude Code users**:
+specs and architecture as living documents and source of truth, evolution via
+spec deltas and ADRs, finalization with a judge-until-convergence loop and a
+human gate — all driven by an external orchestrator over a headless core.
+
+**Status:** Milestone 1 (skeleton) implemented — strict schemas, fold-engine
+with byte-for-byte parity with OpenSpec, ADR log with projected state,
+derived state machine, cumulative gates, judge-until-convergence loop,
+headless invocation (SDK/CLI) and the full CLI surface.
+
+```
+trueline init                 # .trueline/ skeleton + config.yaml
+trueline propose <id>         # phases: propose → plan → decompose → build
+trueline validate [<id>|--ci] # battery of checks (drift) / post-merge net
+trueline finalize <id>        # refactor short-circuit or judge loop
+trueline approve|reject <id>  # human gate of finalization
+trueline status [<id>]        # derived state + next step
+trueline adr list             # decision log with display numbering
+```
+
+## Documents
+
+- [docs/DESIGN.md](docs/DESIGN.md) — conceptual design (v5). In conflict with the spec, the design wins.
+- [docs/M1-SPEC.md](docs/M1-SPEC.md) — technical specification of Milestone 1 (r4, FINAL): the source of truth of the implementation.
+- [docs/M1-HANDOFF.md](docs/M1-HANDOFF.md) — implementation state, agenda and working style.
+
+## License
+
+MIT — see [LICENSE](LICENSE). The fold-engine parity suite is translated
+from the OpenSpec test suite (MIT) — see
+[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).

trueline-0.1.0.dev0/README.md

@@ -0,0 +1,33 @@
+# trueline
+
+**Spec-Driven Development (SDD) framework for Claude Code users**:
+specs and architecture as living documents and source of truth, evolution via
+spec deltas and ADRs, finalization with a judge-until-convergence loop and a
+human gate — all driven by an external orchestrator over a headless core.
+
+**Status:** Milestone 1 (skeleton) implemented — strict schemas, fold-engine
+with byte-for-byte parity with OpenSpec, ADR log with projected state,
+derived state machine, cumulative gates, judge-until-convergence loop,
+headless invocation (SDK/CLI) and the full CLI surface.
+
+```
+trueline init                 # .trueline/ skeleton + config.yaml
+trueline propose <id>         # phases: propose → plan → decompose → build
+trueline validate [<id>|--ci] # battery of checks (drift) / post-merge net
+trueline finalize <id>        # refactor short-circuit or judge loop
+trueline approve|reject <id>  # human gate of finalization
+trueline status [<id>]        # derived state + next step
+trueline adr list             # decision log with display numbering
+```
+
+## Documents
+
+- [docs/DESIGN.md](docs/DESIGN.md) — conceptual design (v5). In conflict with the spec, the design wins.
+- [docs/M1-SPEC.md](docs/M1-SPEC.md) — technical specification of Milestone 1 (r4, FINAL): the source of truth of the implementation.
+- [docs/M1-HANDOFF.md](docs/M1-HANDOFF.md) — implementation state, agenda and working style.
+
+## License
+
+MIT — see [LICENSE](LICENSE). The fold-engine parity suite is translated
+from the OpenSpec test suite (MIT) — see
+[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).

trueline-0.1.0.dev0/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,38 @@
+# Avisos de terceiros
+
+## OpenSpec (MIT)
+
+A suíte de testes de paridade do fold-engine deste repositório (em `tests/`,
+identificada nos cabeçalhos dos próprios arquivos) é uma **tradução para
+Python/pytest da suíte de testes do projeto OpenSpec**
+(<https://github.com/Fission-AI/OpenSpec>), usada aqui como especificação
+executável da gramática de deltas de spec e do algoritmo de merge. O código de
+referência original é `src/core/parsers/requirement-blocks.ts` e
+`src/core/specs-apply.ts` daquele projeto.
+
+Conforme exigido pela licença MIT do OpenSpec, o aviso de copyright e a
+permissão originais são reproduzidos integralmente abaixo:
+
+```
+MIT License
+
+Copyright (c) 2024 OpenSpec Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```