@rlabs-cl/arketum 0.0.0-stage → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,140 @@
+# Changelog
+
+Every published version of Arketum has an entry here with what changes for the
+people who use it. Changes accumulate under `## Unreleased` as they are made and
+move to the version's own section when it is published.
+
+If a version changes the store format (the `.arketum/` folder), its entry says
+the new format version and that the store has to be updated with the update
+action (`action: actualizar_almacen`).
+
+Versions follow semver: a fix bumps the patch, something new bumps the minor,
+and a new store format or a renamed action bumps the major.
+
+## Unreleased
+
+## 1.0.1
+
+### Fixes
+
+- **License text.** The `LICENSE` shipped in 1.0.0 still opened with a draft
+  notice; it now carries only the license itself. The terms do not change.
+
+## 1.0.0 — Initial release
+
+The first public version. Arketum is an MCP server with a single tool, `build`,
+that governs the lifecycle of software built with agents, from the request to a
+verified close. The agent calls it at every step; each answer says where the
+work stands, what comes next and with what context. Arketum runs nothing and
+calls no model: it suggests, checks what it receives and records the person's
+decisions with their provenance. Apart from the anonymous telemetry the person
+opts into, it makes no network requests.
+
+### Features
+
+- **Projects** declared in `.arketum/proyecto.yaml`: the system's artifacts, each
+  with its archetype (or its stack and component), its root and its
+  dependencies; the declared scaffolding; the input documents; the catalogs and
+  the system shape.
+- **Catalogs** from which archetypes, lanes, system shapes and stacks are
+  resolved by name: the project's own, personal ones and the bundled example
+  catalog, named rather than located (`{ incluido: ejemplo }`). No archetype
+  lives in Arketum's code.
+- **Work units and lanes.** Every piece of work is a unit with a lane, a goal,
+  the chosen steps and, when it applies, a milestone (a deployment, a delivery or
+  a run). The example catalog brings the lanes `nuevo`, `funcionalidad`,
+  `ajuste`, `comprobacion`, `correccion`, `arquetipo`, `migracion`, `digestion`
+  and `despliegue`.
+- **Gates decided by the person.** The person approves, adjusts or rejects what
+  is theirs: what gets built, clashes with what was already decided, the
+  deployment and, at the end of each unit, whether it turned out as wanted. Gates
+  reach the person through a form when the client supports it, through the chat
+  otherwise, and every decision records its channel and when it was made.
+  Process gates can be delegated, with or without a limit of units.
+- **Requirements with versions and states**: functional, technical and decision
+  requirements, each with a short stable id, its statement, its acceptance
+  criterion and its version. The requirements index and the living PRD are
+  computed from the decisions stored one file per decision.
+- **Descent of artifacts.** Each touched artifact is built from the general to
+  the particular, level by level (`L0` to at most `L4`), with coverage,
+  justification, granularity and archetype conformance checked at every step,
+  and fidelity to the file tree at the last one.
+- **Evidence.** Executions, reports and declarations back each step; execution
+  evidence links the requirements it satisfies. When the system shape asks for
+  it, the floor checks and the full end-to-end suite are run through the real
+  path, with fixtures copied verbatim from the catalog.
+- **Closing conditions.** Closing re-delivers every descent against the current
+  archetype and tree and checks the conditions; the project policy is fixed when
+  a unit starts, so whatever is edited by hand to close is not whitewashed.
+- **Retroactive validation.** Closing a unit with its own requirements contrasts
+  what was built with the earlier requirements it touches: contradicted,
+  redundant, mergeable or obsolete.
+- **Drift.** The status contrasts the tree with what was declared and names each
+  finding with its suggestion (legalize it through a gate or correct it with a
+  unit); functional drift re-runs the evidence copied from the requirements.
+- **The person's panel**: a local web page (one per machine, on `127.0.0.1`)
+  with the state of each project, where the person sees what is waiting and
+  decides it.
+- **The batch** (`tanda`): everything waiting for the person in the project,
+  gathered in one place: blocked units first, then gates, confirmations and
+  declarations.
+- **Topics** (`tema`): what is left to talk about, in the person's own words or
+  proposed by the agent, optionally with the unit that would address it.
+- **Audit**: on request, it groups requirements that pursue the same intention
+  and proposes a consolidated PRD as a topic; the gaps and drifts Arketum
+  computes become topics with their proposal.
+- **Parallel or sequential work**: while a subagent builds what is ready, the
+  person keeps defining what comes next; a unit that cannot go on without the
+  person is marked blocked with its reason, without interrupting.
+- **CI**: `arketum ci` re-runs the recorded evidence of the units a change
+  touches and re-checks their close.
+- **Store format 1.** `.arketum/format.yaml` declares the store format version
+  (`version: 1`), written by Arketum. A store with a newer format than the one
+  Arketum knows is neither read nor written: every action, the status and the
+  panel refuse it and ask to update Arketum. `action: actualizar_almacen`
+  updates a store to the current format.
+- **Anonymous usage telemetry, only if the person accepts.** Until the
+  installation decides, the question waits among the person's pending items (the
+  batch, the panel and the status), and the agent is asked once to put it to
+  them in the chat; it is answered in the chat (`action: telemetria` with
+  `acepta` and `cita`), the batch, the panel or the terminal
+  (`arketum telemetria --acepto` / `--no`), and once decided it is never asked
+  again. The decision is kept in `~/.arketum/`. Accepted, at most one summary a
+  day is sent after answering, with a 2-second limit and no retries: the
+  version, the install channel, the operating system family, the MCP client's
+  declared name, how many projects and days of use, and per project (by a hash
+  that cannot be reversed) its units per lane, its gates per channel with their
+  median wait and its topics. Never any text, path or name, and each event asks
+  the receiving service not to derive a location from the connection nor build
+  a person profile. `arketum telemetria` prints exactly what would be sent,
+  `--probar` sends one test event and says whether it arrived, and
+  `ARKETUM_TELEMETRIA=0` turns it off. It is the only thing that leaves the
+  machine; the destination is declared by the distribution, and a build without
+  it sends nothing.
+
+### Flows
+
+1. **Start.** Without `.arketum/`, any call returns how to start for that
+   folder: an empty folder opens a `nuevo` unit; a folder with only documents
+   starts from them as the project's base; a folder with code opens a
+   `digestion` unit that proposes the base structure for the person to confirm.
+2. **Situate and open.** The agent classifies the request against the
+   requirements index and opens a unit with a lane and a goal; the person
+   confirms the lane and its steps, and Arketum takes a snapshot of the tree.
+3. **Phase 1, elicitation.** The analyst (talks with the person) and the
+   architect (deduces the technical side) hand in their parts; the person
+   confirms in the PRD gate what will be done.
+4. **Phase 2, implementation.** Architecture, the descent of each touched
+   artifact and the execution evidence, with the implementation roles the
+   system shape suggests.
+5. **Small changes** go through the `ajuste` lane: the person's literal request,
+   a short radius and the inherited descent, with its size measured by Arketum.
+6. **Deploy.** The `despliegue` lane starts with an infrastructure survey; what
+   the person has to obtain outside the session becomes a questionnaire, and the
+   deployment milestone is met when the person confirms it was deployed and ran.
+   Arketum never stores a secret, only its reference.
+7. **Close**, with the closing conditions, the boundaries of each artifact and
+   the retroactive validation; then the person confirms whether it is what they
+   wanted.
+8. **Keep going**: status, drift, the batch, topics and the audit, from the
+   agent or from the panel.

package/LICENSE

@@ -0,0 +1,42 @@
+LICENCIA DE USO DE ARKETUM
+
+Copyright (c) 2026 rlabs-cl. Todos los derechos reservados.
+
+Arketum (el «Software») es software propietario de rlabs-cl. Esta licencia no
+es una licencia de código abierto.
+
+1. Concesión. rlabs-cl concede a quien recibe el Software, de forma no
+   exclusiva, intransferible y revocable, el derecho a instalarlo y usarlo, tal
+   como se distribuye, para su propio trabajo.
+
+2. Lo que no se concede. Salvo autorización previa y por escrito de rlabs-cl,
+   no se concede el derecho a:
+   a) copiar el Software, salvo lo necesario para instalarlo y usarlo;
+   b) modificarlo, adaptarlo, traducirlo o crear obras derivadas de él;
+   c) redistribuirlo, publicarlo, venderlo, alquilarlo, prestarlo o ponerlo a
+      disposición de terceros, con o sin modificaciones;
+   d) descompilarlo, desensamblarlo o aplicarle ingeniería inversa, salvo en la
+      medida en que la ley aplicable lo permita expresamente pese a esta
+      limitación;
+   e) sublicenciarlo, ni ceder los derechos de esta licencia.
+
+3. Componentes de terceros. El Software incluye componentes de terceros que se
+   rigen por sus propias licencias, recogidas en el fichero
+   THIRD-PARTY-NOTICES que lo acompaña. Esta licencia no limita los derechos
+   que esas licencias conceden sobre esos componentes.
+
+4. Avisos. No se pueden quitar ni alterar los avisos de derechos de autor, de
+   esta licencia ni de THIRD-PARTY-NOTICES.
+
+5. Sin garantía. EL SOFTWARE SE ENTREGA «TAL CUAL», SIN GARANTÍA DE NINGÚN
+   TIPO, EXPRESA O IMPLÍCITA, INCLUIDAS, SIN LIMITARSE A ELLAS, LAS DE
+   COMERCIABILIDAD, IDONEIDAD PARA UN FIN DETERMINADO Y NO INFRACCIÓN.
+
+6. Limitación de responsabilidad. EN NINGÚN CASO rlabs-cl SERÁ RESPONSABLE DE
+   RECLAMACIONES, DAÑOS U OTRAS RESPONSABILIDADES, YA SEA POR CONTRATO, ACTO
+   ILÍCITO O DE OTRO MODO, QUE SURJAN DEL SOFTWARE, DE SU USO O DE OTRAS
+   OPERACIONES CON ÉL.
+
+7. Terminación. Esta licencia termina sin aviso si se incumple cualquiera de
+   sus términos. Al terminar, hay que dejar de usar el Software y borrar las
+   copias que se tengan.

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+# Arketum
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A verified lifecycle for software built with agents: from the request to a verified close.**
+
+Arketum is an MCP server with a single tool, `build`. The agent calls it at every step; each answer says where the work stands, what comes next and with what context. Arketum runs nothing and calls no model: it suggests what to do, checks what it receives and records the person's decisions with their provenance.
+
+What it ensures:
+
+- what gets built answers what was asked, and the person confirms what will be done before it is built;
+- every artifact is built from the general to the particular, checking coverage, justification, granularity and conformance to its archetype at each step, and faithful to the file tree;
+- every file in the project is claimed by an archetype or is declared scaffolding, and no change escapes what the unit declared;
+- requirements have versions and states, and every change is tied to one.
+
+What it does not ensure: that the decisions are good. Checking that a decision was respected can be automated; judging its merit cannot.
+
+## Install
+
+Node.js 20 or later. Register this command as a stdio MCP server in your client:
+
+```bash
+npx -y @rlabs-cl/arketum
+```
+
+For example, in Claude Code:
+
+```bash
+claude mcp add --scope user arketum -- npx -y @rlabs-cl/arketum
+```
+
+Or in any MCP client:
+
+```json
+{
+  "mcpServers": {
+    "arketum": { "command": "npx", "args": ["-y", "@rlabs-cl/arketum"] }
+  }
+}
+```
+
+Installed globally (`npm install -g @rlabs-cl/arketum`), the `arketum` executable is the same server; `arketum ci …` re-runs the recorded evidence of units in CI and `arketum panel …` starts the local status panel (one per machine, on `127.0.0.1`).
+
+If your client cannot show forms to the person (elicitation), set `ARKETUM_GATES=chat` and the agent will ask the gate decisions in the chat.
+
+## How it works
+
+1. **Start.** In an empty folder, an existing project or a folder with only documents, the first call returns how to start: the minimal `.arketum/proyecto.yaml` and the first unit to open.
+2. **Open a unit** with a lane (new project, feature, small fix, correction, deployment…) and a goal; the person confirms the lane and its steps.
+3. **Phase 1, elicitation.** An analyst (talks with the person) and an architect (deduces the technical side) build the PRD; the person approves what will be built.
+4. **Phase 2, implementation.** Each touched artifact descends its ladder level by level, and execution evidence links the requirements it satisfies.
+5. **Close.** Arketum re-checks every descent against the current archetype and tree, and the closing conditions.
+
+The person is asked what is theirs to decide; the process steps can be delegated. Everything Arketum remembers lives as plain text in the project's `.arketum/` folder.
+
+What changes in each version, and the store format version it knows, is in `CHANGELOG.md`. Arketum's own messages are in Spanish for now.
+
+## What it sends
+
+Only if you accept: an anonymous usage summary, at most once a day. Until you decide, the question waits among your pending items (in the batch, the panel and the status), and your agent can ask you in the chat; without an answer, or with a no, nothing is counted or sent. Once you decide, it is never asked again. To opt in from your terminal:
+
+```sh
+arketum telemetria --acepto
+```
+
+ The summary says the version, how it was installed, the operating system family, the name your MCP client declares, how many projects and days it was used and, per project (identified only by a hash that cannot be reversed), its units per lane, its gates per channel with how long they waited for you, and how many topics are open and closed. It never carries any text, path, name or code, and it asks the receiving service not to derive your location from the connection and not to build a person profile. `arketum telemetria` prints exactly what would be sent, `arketum telemetria --probar` sends one test event and tells you whether it arrived, `arketum telemetria --no` stops it, and `ARKETUM_TELEMETRIA=0` turns it off on this machine whatever was decided. Everything else stays on your machine.
+
+## License
+
+Proprietary software of rlabs-cl: you may use it, but not copy, modify, redistribute, decompile or sublicense its code; it comes without warranty. See `LICENSE`. Third-party dependencies are governed by their own licenses, listed in `THIRD-PARTY-NOTICES`.