From ff8adc15f7992a5d1df7e38d10b8cde3fc687a0f Mon Sep 17 00:00:00 2001 From: skobeltsyn Date: Thu, 12 Nov 2026 11:20:01 +0300 Subject: [PATCH 1/2] docs: describe Agents.KT as an AI factory for software and embodied agents Add a partner handoff at docs/ai-factories.md and point AGENTS.md at it. The factory is a line of Agent stations. Software tools and body tools share that line. Shipped claims stay in the README and release-metadata.yaml. --- AGENTS.md | 128 +++++++++++++++++++++++ docs/ai-factories.md | 68 ++++++++++++ sdlc/agents/parts/extreme-programming.md | 35 +++++++ sdlc/agents/parts/language.md | 125 ++++++++++++++++++++++ sdlc/agents/parts/project/legacy.md | 34 ++++++ sdlc/agents/parts/project/new_wave.md | 55 ++++++++++ sdlc/agents/parts/project/project.md | 19 ++++ sdlc/agents/parts/requirements.md | 79 ++++++++++++++ sdlc/agents/parts/transcripts.md | 7 ++ 9 files changed, 550 insertions(+) create mode 100644 AGENTS.md create mode 100644 docs/ai-factories.md create mode 100644 sdlc/agents/parts/extreme-programming.md create mode 100644 sdlc/agents/parts/language.md create mode 100644 sdlc/agents/parts/project/legacy.md create mode 100644 sdlc/agents/parts/project/new_wave.md create mode 100644 sdlc/agents/parts/project/project.md create mode 100644 sdlc/agents/parts/requirements.md create mode 100644 sdlc/agents/parts/transcripts.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..28df3d7 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,128 @@ +# Agents.KT + +_Source: [sdlc/agents/parts/project/project.md](sdlc/agents/parts/project/project.md)._ + +## Project + +Agents.KT is the JVM runtime for an AI factory. A factory is a line of `Agent` stations: one input type, one output type, one job. The same line builds a software agent or an embodied agent. Software tools are compilers, repos, HTTP, and MCP. Body tools are sensors and actuators, attached the same way. The handoff for a partner agent is [docs/ai-factories.md](docs/ai-factories.md). The product site is [agents-kt.dev](https://agents-kt.dev/). The Maven coordinate is `ai.deep-code:agents-kt`. The license is MIT, held by Deep-Code.AI. The repository is [Deep-CodeAI/Agents.KT](https://github.com/Deep-CodeAI/Agents.KT). + +The published version, the provider count, and the protocol status live in [release-metadata.yaml](release-metadata.yaml). [README.md](README.md) tracks that file. `ReleaseMetadataConsistencyTest` fails when a surface drifts. The [wiki](https://github.com/Deep-CodeAI/Agents.KT/wiki) is the learning path. When the wiki names an older published version, `release-metadata.yaml` and the README win. + +| Path | Holds | +| --- | --- | +| `AGENTS.md` | This law, assembled from `sdlc/agents/parts/project/`. Edit the part, then copy the same text into the matching import block. | +| [docs/ai-factories.md](docs/ai-factories.md) | Partner handoff: one factory, software lines and embodied lines. | +| `README.md` | Product contract: security model, shipped surface, limitations, documentation index. | +| `docs/` | In-repo guides. Start with [docs/testing.md](docs/testing.md), [docs/source-layout.md](docs/source-layout.md), [docs/composition.md](docs/composition.md), [docs/threat-model.md](docs/threat-model.md). The README Documentation list names the rest. | +| [Wiki Home](https://github.com/Deep-CodeAI/Agents.KT/wiki) | Learning path, from Installation through Best Practices. | +| `release-metadata.yaml` | `currentRelease`, `developmentVersion`, `providers`, and `protocols`. | +| `src/main/kotlin/agents_engine/` | Core runtime. | +| `agents-kt-*` | Feature modules named in `settings.gradle.kts`. | +| `sdlc/` and `tasks/` | Adopted Tatenergo.AI snapshot. Framework work stays in `src/` and the `agents-kt-*` modules. | + +JDK 21 or newer. Kotlin version and the dependency line are the ones the README Current Release section states. The Gradle wrapper is the build. `./gradlew build` is the environment check in [Building From Source](https://github.com/Deep-CodeAI/Agents.KT/wiki/Building-From-Source). + + + + + +_Source: [sdlc/agents/parts/project/legacy.md](sdlc/agents/parts/project/legacy.md)._ + +## Authority + +Read these, in this order, before changing a claim or a boundary: + +1. [release-metadata.yaml](release-metadata.yaml) for a version, a provider count, or a protocol status (`shipped`, `partial`, `experimental`, `spiked`). +2. [README.md](README.md) for the security model, the shipped list, and the known limitations. +3. [docs/threat-model.md](docs/threat-model.md) for which boundary the runtime enforces and which boundary the deployer owns. +4. The matching page under `docs/`. +5. The wiki page for the same topic, as the long-form narrative. [Best Practices](https://github.com/Deep-CodeAI/Agents.KT/wiki/Best-Practices) holds the DO and DON'T list. + +### What the runtime owns + +- Typed `Agent` contracts and the composition operators. +- Per-skill tool authorization and typed tool handles. +- MCP client and server surfaces on the same tool and skill shape. +- Permission manifests, declarative tool policies, and runtime audit correlation. +- JSONL audit export and the OTel, LangSmith, and Langfuse adapters through `ObservabilityBridge`. +- Local-first JVM execution. Ollama is the default local provider. Cloud providers are opt-in. + +The README section "What Agents.KT Owns" is the full statement. [docs/permission-manifest.md](docs/permission-manifest.md) and [docs/cli.md](docs/cli.md) cover the manifest and the `agents-kt` CLI (`generate`, `inspect`, `verify`). + +### What the deployer owns + +The README section "What Agents.KT Does Not Own" is the full statement. The durable split: + +| Boundary | Owner | +| --- | --- | +| Legal classification of a use case | Counsel and the compliance team. The runtime emits evidence. | +| Side effects inside a Kotlin tool lambda | The deployer. Layer 1 gates declared filesystem-path arguments. `processTool` adds the Layer 2 OS sandbox for subprocess tools. | +| Public MCP request rate | The gateway, plus `McpServer` auth and policy. | +| Prompt-injection classification | The deployer, through `onBeforeTurn`. | +| Vector storage, an eval product, hosted orchestration | The surrounding system. The runtime is the typed JVM boundary under those integrations. | + +A change that widens one of these claims updates the README, the threat model, and `release-metadata.yaml` in the same edit. + + + + + +_Source: [sdlc/agents/parts/project/new_wave.md](sdlc/agents/parts/project/new_wave.md)._ + +## Working on the runtime + +### Modules + +`settings.gradle.kts` is the module list. The root project `agents-kt` holds `src/main/kotlin/agents_engine/`. Feature modules stay out of the core classpath: + +| Module | Role | +| --- | --- | +| `agents-kt-ksp` | `@Generable` metadata. `kotlin-reflect` stays optional. | +| `agents-kt-no-reflect-test` | Consumer classpath that excludes `kotlin-reflect`. | +| `agents-kt-manifest` | Deterministic permission manifests. | +| `agents-kt-cli` | `generate`, `inspect`, `verify` outside Gradle. | +| `agents-kt-observability`, `agents-kt-otel`, `agents-kt-langsmith`, `agents-kt-langfuse` | Audit export and bridges. | +| `agents-kt-rag`, `agents-kt-rag-langchain4j`, `agents-kt-rag-spring-ai` | RAG seam. | +| `agents-kt-identity`, `agents-kt-dir` | AGNTCY Identity and DIR. | +| `agents-kt-detekt` | `ToolBodyForbiddenApis` and `ToolCapabilityExtractor`. | +| `agents-kt-whisper-jni` | Optional native Whisper backend. | + +### Packages + +The wiki [Architecture Overview](https://github.com/Deep-CodeAI/Agents.KT/wiki/Architecture-Overview) describes the original four packages: `core`, `composition`, `model`, `generation`. The tree also has `a2a`, `agui`, `agntcy`, `content`, `mcp`, `nlweb`, `runtime`, `sandbox`, `testing`, `x402`, and `internal`. Match the package that already owns the behavior. + +[docs/source-layout.md](docs/source-layout.md) is the file rule. One top-level type per file. The file name is the type name. A sealed type stays with its direct subtypes. `./gradlew checkOneTypePerFile` enforces it. A real sealed-ADT exception goes in `config/one-type-per-file-allowlist.txt` with a `# sealed-ADT: keep` reason. The allowlist only shrinks. + +### Agent shape + +Follow the wiki [Best Practices](https://github.com/Deep-CodeAI/Agents.KT/wiki/Best-Practices) and [Agent and Type Contract](https://github.com/Deep-CodeAI/Agents.KT/wiki/Agent-and-Type-Contract). + +- One agent, one job. A second job is a second agent composed with `then`, `/`, `forum`, `.loop`, `.branch`, or `handoff`. +- Skill and knowledge descriptions say when the model should pick them. Ambiguous skill routing throws `SkillRoutingException`. Predicate `skillSelection { }` stays the path when the input already decides. +- Tool allowlists take typed handles from `tool(...)`. String names stay for built-ins and MCP names discovered at runtime. +- An agentic agent sets `budget { maxTurns = N }`. A loop has an exit. `maxAgentDepth` bounds nested re-entry. +- Each agent instance is placed once. A second placement throws at construction. Reuse goes through a factory. [Single-Placement Rule](https://github.com/Deep-CodeAI/Agents.KT/wiki/Single-Placement-Rule). +- Agents pass data through typed input and output, or through `MemoryBank`. A public signature stays a concrete `IN` and `OUT`. +- Structured model output uses `@Generable` and `@Guide`. A long prompt lives in a classpath resource and loads with `loadResource`. +- Knowledge entries hold no secrets. +- Public API on the 0.x line stays additive. A behavior change is named in the CHANGELOG. + +### Verification + +[docs/testing.md](docs/testing.md) is the in-repo test guide. The wiki [Building From Source](https://github.com/Deep-CodeAI/Agents.KT/wiki/Building-From-Source) is the environment guide. + +| Command | When | +| --- | --- | +| `./gradlew test` | Before a commit. Excludes `live-llm`, `live-mcp`, and `interactive`. | +| `./gradlew :test --tests "pkg.Class"` | One class. Scope the module. A root-wide `test --tests` also hits modules that lack that class. | +| `./gradlew detekt` | With the change. `detekt.yml` holds new code to the rules. The baseline only shrinks. | +| `./gradlew check` | Includes `checkOneTypePerFile`, `checkReadmeVersion`, and `checkDetektBaseline`. | +| `./gradlew integrationTest` | LLM client or agentic-loop work. Needs Ollama. | +| `./gradlew mcpIntegrationTest` | MCP client or server work. Needs `MCP_REDMINE_URL`. | +| `./gradlew pitest` | After a new behavior, to see mutants the tests leave alive. | + +Unit tests inject a `ModelClient`. Live tests stay tagged. Linux sandbox tests (`bwrap`, `firejail`) need a Linux kernel and skip on macOS. CI runs them on Ubuntu. + +A reported defect gets a regression test that fails on the current code before the fix. An existing assertion stays. When a contract change forces an edit, the test name and the contract that replaced it go in the task note. + + diff --git a/docs/ai-factories.md b/docs/ai-factories.md new file mode 100644 index 0000000..7094cc9 --- /dev/null +++ b/docs/ai-factories.md @@ -0,0 +1,68 @@ +# AI factories on Agents.KT + +Handoff for a partner agent. This file is the project picture. Shipped behavior lives in [README.md](../README.md) and [release-metadata.yaml](../release-metadata.yaml). When this file and those two disagree about a version, a provider, or a protocol, those two win. + +## Aim + +Agents.KT is the runtime for building an AI factory. A factory is a repeatable line: a typed job goes in, bounded stations do one job each, and a typed result comes out. The same line shape builds two kinds of agent. + +| Factory | The job | The tools | The result | +| --- | --- | --- | --- | +| Software | A spec, a ticket, a file, or a user turn | Compilers, repos, HTTP, MCP servers, other agents | A patch, a document, a decision, or a tool result | +| Embodied | A mission, a pose, or a sensor frame | Cameras, drivers, grippers, navigation, motion primitives | A command a controller can run, or a stop | + +One runtime serves both. The body is a set of tools and typed messages. It is a second product of the same factory, and it is a second framework. + +## What a station is + +A station is `Agent`: one input type, one output type, one job. A skill on that station allowlists the tools that station may call. The compiler checks that one station's output is the next station's input. + +A line is composition: + +| Line | Code | Use | +| --- | --- | --- | +| Sequence | `a then b` | Software: parse, then generate, then review. Embodied: perceive, then plan, then act. | +| Same input, concurrent stations | `a / b` | Two reviewers, or two sensors, on one workpiece. | +| Council | `forum { }` | Several stations, one captain, one verdict. | +| Repeat until done | `.loop { }` | Refine a patch, or replan while the goal is open. The loop has an exit. | +| Route on type | `.branch { }` | Send a sealed result to the station that owns that case, including a stop. | +| Hand off | `triage handoff { }` | Pass the typed input to a specialist. The specialist does not receive the source history. | + +Each station instance sits on one line. A second use is a new instance from a factory function. Stations pass work through typed input and output, or through `MemoryBank`. + +## What the factory freezes before a shift + +Before a line runs, the factory can show the boundary: + +- The permission manifest lists agents, skills, tools, policies, providers, and budgets, and hashes that graph. +- A budget caps turns, tool calls, time, and tokens. `maxAgentDepth` caps nested calls. +- A tool policy records filesystem, network, and environment scope. Declared filesystem paths are gated in the JVM. Subprocess tools can run in an OS sandbox. +- Runtime events carry the manifest hash. A JSONL log and a tamper-evident tool ledger record what the line did. +- A human gate is an interceptor or a HITL interrupt. For an embodied line, a stop is a station outcome, not a sentence in a prompt. + +The deployer still owns legal classification, rate limits on public MCP, prompt-injection detection, and any safety controller under the actuators. The runtime emits evidence and enforces the boundaries declared in code. [docs/threat-model.md](threat-model.md) is the table of which layer enforces which boundary. + +## Software factory, as it stands + +This repository is that factory's runtime. Kotlin on JDK 21+. Maven coordinate `ai.deep-code:agents-kt`. License MIT, Deep-Code.AI. Product site [agents-kt.dev](https://agents-kt.dev/). Source [github.com/Deep-CodeAI/Agents.KT](https://github.com/Deep-CodeAI/Agents.KT). + +A software line is a library inside a JVM service, an MCP server, an A2A peer, or a same-JVM swarm. Local models start with Ollama. Cloud providers are opt-in. The provider count and the protocol status (`mcp`, `a2a`, `agui`, `nlweb`, `x402`, `agntcy`) are the fields in `release-metadata.yaml`. + +Core code is `src/main/kotlin/agents_engine/`. Feature modules are the `agents-kt-*` projects in `settings.gradle.kts`. `sdlc/` and `tasks/` are an adopted Tatenergo.AI snapshot. Factory work goes in `src/` and the `agents-kt-*` modules. + +## Embodied factory, as a target + +The embodied line uses the same station, the same allowlist, and the same manifest. A camera frame is an input type. A motion primitive is a tool. A pose is an output type. The partner agent designs that line in types and tools. + +This repository has no robot, ROS, or actuator package. Do not treat a body driver as shipped code. Attach a body by giving the act station tools whose arguments are commands the existing controller already accepts, with a budget, a policy, and a branch whose stop case runs before motion. + +## What the partner agent does with this + +1. Read [README.md](../README.md) for the security model and the shipped list. +2. Read `currentRelease`, `providers`, and `protocols` in [release-metadata.yaml](../release-metadata.yaml) before stating a version. +3. Design a line as `Agent` stations. One station, one job. +4. Choose software tools or body tools. Keep both behind the skill allowlist. +5. Put a stop, a human gate, and a budget on any line that can move code into production or move a body. +6. Verify runtime changes with `./gradlew test`. The in-repo guide is [docs/testing.md](testing.md). The learning path is the [wiki](https://github.com/Deep-CodeAI/Agents.KT/wiki). + +Contributor rules for editing this repository are in [AGENTS.md](../AGENTS.md). diff --git a/sdlc/agents/parts/extreme-programming.md b/sdlc/agents/parts/extreme-programming.md new file mode 100644 index 0000000..35af42d --- /dev/null +++ b/sdlc/agents/parts/extreme-programming.md @@ -0,0 +1,35 @@ +## Test-first + +The minimal unit of work is one use case. The use case proceeds in baby steps. A baby step ends with a green test, each fact living once, and the architecture of the types that step touched still correct. + +### Baby step + +One baby step adds one behavior of the use case. + +1. Write one failing test for that behavior. +2. Make the test compile. +3. Make the test green with the smallest production change. +4. Remove duplication. Each fact lives once. +5. Restore the architecture. One type keeps one outcome. One file holds one entity. The layer and the package match the new-wave part. + +The next baby step starts from that tree. The use case is done when every behavior has finished a baby step. + +The run ends with every test green. + +Each test suite includes exploit tests under `tests/security`. An exploit calls the use case as another actor, with another actor's id, or with a privileged field. The test is green when the system refuses the call and the other actor's row stays unchanged. The test is red when the exploit reads or writes that row. + +An existing test stays as it is. An edit to an existing test happens when the edit is inevitable: the assertion encodes a contract that was replaced, or the test fails to compile because that contract's types changed. The task file records the test name and the reason. The old assertion is the record of application logic. Replacing it replaces that logic, and a wrong reason ships the wrong logic. + +| After the step | Holds | +| --- | --- | +| Tests | The new test is green. Every test that was green at the start of the run is green. | +| Repetition | One fact, one branch, and one query each live in one place. | +| Architecture | A controller method calls one use case. Domain stays free of HTTP framework types. | + +bad: `Add the behaviors of the use case, then clean the duplicates and the packages at the end.` + +good: `The test for one behavior is red, then green. The duplicate leaves. The type still has one outcome. The next behavior starts there.` + +bad: `Change the old assertion so the suite goes green.` + +good: `The old assertion stays. The new test is green. When the old assertion has to change, the task file names the test and the contract that replaced it.` diff --git a/sdlc/agents/parts/language.md b/sdlc/agents/parts/language.md new file mode 100644 index 0000000..b9dc427 --- /dev/null +++ b/sdlc/agents/parts/language.md @@ -0,0 +1,125 @@ +## Language + +Use positive expressions. + +bad: `This is not X, not Y - Z` +good: `This is Z`. + +Skip bracketed asides. + +bad: `this X is so amazing innovation in Y (excitement)` +good: `Innovation X in Y makes Z significantly better` + +Use quantities. + +bad: `there are too much X for Y` +good: `For Y you need Z but given X` + +State the amounts on both sides of a limit. + +bad: `You have only 10USD left - it is impossible to do X` +good: `X costs YUSD, given 10USD` + +Keep one sentence on one mechanism. + +bad: `X, Y, Z - not by A, not by B.. - by ... F` +good: `By B using ... incorporating F we achive|get|obtain X with Y and Z.` + +Drop words that carry no fact. + +bad: `X, Y, Z, before they A.` +good: `X, Y.` + +A sentence that names an absence and stops is empty. Leave it out. + +bad: `What we are not proposing: X` + +Use the shortest wording that still carries the fact. + +bad: `One venue uplink, one org API key, 20 concurrent agent sessions` +good: `20 concurrent agent sessions using same network and API key` + +bad: `With 20 tables and 6 facilitators, a director flying blind discovers stuck tables at the debrief, which is too late.` +good: `director should be able to monitor 20 tables and 6 facilitators using ....` + +The file name already holds the title. The body holds the content. + +bad: `AI Theater — the whole program, in one table` +good: `AI Theater` + +Put totals in the lead and the breakdown under them. + +bad: `120 participants · one computer each · 240 minutes · 25 tasks · 9 gates at 80% green = 96 of 120. Computer setup runs before the event, outside the budget.` +good: `4 hours program, 120 participants, 25 tasks` + +Add a section when the text is unclear without it. + +bad: `Section Reading the X` +good: a heading appears when the paragraph under it is unclear without that heading. + +Name the objects a level is responsible for. + +bad: `Level 2 walks all 120 machines: the agent is available, the dataset is in place, the videos are on disk.` +good: `Level 2 is responsible for agent availability, datasets in place, videos on disk, and handouts at all 120 seats.` + +A schedule row states who runs the block and what the block contains. + +bad: `Who runs the day; a map of 5 blocks, 3 breaks, and 25 tasks; an 80% threshold; how to call for help; a simulated company; voice input with the Whisper model on each machine. 9 slides` +good: `Who runs the day; a description of the 5 blocks; how to call for help and what to do when the pace falls short of the 80% threshold, with a chance to catch up with support; the simulated environment (company, messenger, mail, and the rest); voice input with the Whisper model on each machine` + +A heading names the thing. + +bad: `Source material (checked, with sources)` +good: `Cases` + +State the structure in place order. + +bad: `The five-level pyramid is read from the top: purpose sets everything else` +good: `The pyramid has five levels. The domain sits above. Work with the hardware sits below.` + +Name the object of every verb. + +bad: `Reversibility: switching the harness is available for 6 of 7 tools in part 5, and editing the regulation takes a day` +good: `Reversibility: switching the harness is available for 6 of 7 tools in part 5, and editing the rules file takes a day` + +A sentence that reports a label and stops is empty. State the two items. + +bad: `Benjamin Graham described two ways to handle money and called both of them existing.` +good: `Benjamin Graham described two ways to handle money: 1) 2)` + +Put the operation and its result in one clause. + +bad: `Investing is an operation that, after analysis, promises safety of principal and an acceptable return.` +good: `Investing is an operation that secures safety of principal and an acceptable return.` + +Name the metrics and the shared cause. + +bad: `Two numbers measure different things: the first is hardware load, the second is the financial result of the pilots.` +good: `The 2 metrics shown reflect hardware load and the financial result of the pilots, with one shared factor behind the bad outcome: the decision to start was made without a measurement before the purchase.` + +Keep the term. A calque hides it. + +bad: `Frame: two ways to handle money` +good: `Two frameworks for working with funds` + +Describe the result. Address the reader in zero sentences. + +bad: `After the talk, you roll the direction you need into your company's playbook` +good: `The talk makes it possible to build a playbook for the chosen directions` + +A short sentence still names its subject and the mechanism. + +bad: `Hence the second author.` +good: `Graham's margin-of-safety calculation needs modern approaches added to it. Nassim Taleb's approach fits for black swans and antifragility: designing the system's response to a model-generation change, a vendor refusal, attacks on the perimeter, and many others.` + +One result, then the difference in method. + +bad: a paragraph that restates both definitions before the test. +good: `Investing and speculation serve one result: the return and growth of invested resources. The difference is the method. In the first case the return comes from the work of the asset. In the second it comes from revaluing the asset.` + +The title is the claim. Counts and sources sit in the body. + +bad: `Benjamin Graham's and Nassim Taleb's principles applied to investments in artificial intelligence. Six vectors, entry and exit thresholds, a source for each number.` +good: `Principles of investing in artificial intelligence.` + +Texts use verifiable facts and metrics. A diagram replaces a paragraph when the diagram carries the same facts. diff --git a/sdlc/agents/parts/project/legacy.md b/sdlc/agents/parts/project/legacy.md new file mode 100644 index 0000000..4c77756 --- /dev/null +++ b/sdlc/agents/parts/project/legacy.md @@ -0,0 +1,34 @@ +## Authority + +Read these, in this order, before changing a claim or a boundary: + +1. [release-metadata.yaml](release-metadata.yaml) for a version, a provider count, or a protocol status (`shipped`, `partial`, `experimental`, `spiked`). +2. [README.md](README.md) for the security model, the shipped list, and the known limitations. +3. [docs/threat-model.md](docs/threat-model.md) for which boundary the runtime enforces and which boundary the deployer owns. +4. The matching page under `docs/`. +5. The wiki page for the same topic, as the long-form narrative. [Best Practices](https://github.com/Deep-CodeAI/Agents.KT/wiki/Best-Practices) holds the DO and DON'T list. + +### What the runtime owns + +- Typed `Agent` contracts and the composition operators. +- Per-skill tool authorization and typed tool handles. +- MCP client and server surfaces on the same tool and skill shape. +- Permission manifests, declarative tool policies, and runtime audit correlation. +- JSONL audit export and the OTel, LangSmith, and Langfuse adapters through `ObservabilityBridge`. +- Local-first JVM execution. Ollama is the default local provider. Cloud providers are opt-in. + +The README section "What Agents.KT Owns" is the full statement. [docs/permission-manifest.md](docs/permission-manifest.md) and [docs/cli.md](docs/cli.md) cover the manifest and the `agents-kt` CLI (`generate`, `inspect`, `verify`). + +### What the deployer owns + +The README section "What Agents.KT Does Not Own" is the full statement. The durable split: + +| Boundary | Owner | +| --- | --- | +| Legal classification of a use case | Counsel and the compliance team. The runtime emits evidence. | +| Side effects inside a Kotlin tool lambda | The deployer. Layer 1 gates declared filesystem-path arguments. `processTool` adds the Layer 2 OS sandbox for subprocess tools. | +| Public MCP request rate | The gateway, plus `McpServer` auth and policy. | +| Prompt-injection classification | The deployer, through `onBeforeTurn`. | +| Vector storage, an eval product, hosted orchestration | The surrounding system. The runtime is the typed JVM boundary under those integrations. | + +A change that widens one of these claims updates the README, the threat model, and `release-metadata.yaml` in the same edit. diff --git a/sdlc/agents/parts/project/new_wave.md b/sdlc/agents/parts/project/new_wave.md new file mode 100644 index 0000000..53df8b1 --- /dev/null +++ b/sdlc/agents/parts/project/new_wave.md @@ -0,0 +1,55 @@ +## Working on the runtime + +### Modules + +`settings.gradle.kts` is the module list. The root project `agents-kt` holds `src/main/kotlin/agents_engine/`. Feature modules stay out of the core classpath: + +| Module | Role | +| --- | --- | +| `agents-kt-ksp` | `@Generable` metadata. `kotlin-reflect` stays optional. | +| `agents-kt-no-reflect-test` | Consumer classpath that excludes `kotlin-reflect`. | +| `agents-kt-manifest` | Deterministic permission manifests. | +| `agents-kt-cli` | `generate`, `inspect`, `verify` outside Gradle. | +| `agents-kt-observability`, `agents-kt-otel`, `agents-kt-langsmith`, `agents-kt-langfuse` | Audit export and bridges. | +| `agents-kt-rag`, `agents-kt-rag-langchain4j`, `agents-kt-rag-spring-ai` | RAG seam. | +| `agents-kt-identity`, `agents-kt-dir` | AGNTCY Identity and DIR. | +| `agents-kt-detekt` | `ToolBodyForbiddenApis` and `ToolCapabilityExtractor`. | +| `agents-kt-whisper-jni` | Optional native Whisper backend. | + +### Packages + +The wiki [Architecture Overview](https://github.com/Deep-CodeAI/Agents.KT/wiki/Architecture-Overview) describes the original four packages: `core`, `composition`, `model`, `generation`. The tree also has `a2a`, `agui`, `agntcy`, `content`, `mcp`, `nlweb`, `runtime`, `sandbox`, `testing`, `x402`, and `internal`. Match the package that already owns the behavior. + +[docs/source-layout.md](docs/source-layout.md) is the file rule. One top-level type per file. The file name is the type name. A sealed type stays with its direct subtypes. `./gradlew checkOneTypePerFile` enforces it. A real sealed-ADT exception goes in `config/one-type-per-file-allowlist.txt` with a `# sealed-ADT: keep` reason. The allowlist only shrinks. + +### Agent shape + +Follow the wiki [Best Practices](https://github.com/Deep-CodeAI/Agents.KT/wiki/Best-Practices) and [Agent and Type Contract](https://github.com/Deep-CodeAI/Agents.KT/wiki/Agent-and-Type-Contract). + +- One agent, one job. A second job is a second agent composed with `then`, `/`, `forum`, `.loop`, `.branch`, or `handoff`. +- Skill and knowledge descriptions say when the model should pick them. Ambiguous skill routing throws `SkillRoutingException`. Predicate `skillSelection { }` stays the path when the input already decides. +- Tool allowlists take typed handles from `tool(...)`. String names stay for built-ins and MCP names discovered at runtime. +- An agentic agent sets `budget { maxTurns = N }`. A loop has an exit. `maxAgentDepth` bounds nested re-entry. +- Each agent instance is placed once. A second placement throws at construction. Reuse goes through a factory. [Single-Placement Rule](https://github.com/Deep-CodeAI/Agents.KT/wiki/Single-Placement-Rule). +- Agents pass data through typed input and output, or through `MemoryBank`. A public signature stays a concrete `IN` and `OUT`. +- Structured model output uses `@Generable` and `@Guide`. A long prompt lives in a classpath resource and loads with `loadResource`. +- Knowledge entries hold no secrets. +- Public API on the 0.x line stays additive. A behavior change is named in the CHANGELOG. + +### Verification + +[docs/testing.md](docs/testing.md) is the in-repo test guide. The wiki [Building From Source](https://github.com/Deep-CodeAI/Agents.KT/wiki/Building-From-Source) is the environment guide. + +| Command | When | +| --- | --- | +| `./gradlew test` | Before a commit. Excludes `live-llm`, `live-mcp`, and `interactive`. | +| `./gradlew :test --tests "pkg.Class"` | One class. Scope the module. A root-wide `test --tests` also hits modules that lack that class. | +| `./gradlew detekt` | With the change. `detekt.yml` holds new code to the rules. The baseline only shrinks. | +| `./gradlew check` | Includes `checkOneTypePerFile`, `checkReadmeVersion`, and `checkDetektBaseline`. | +| `./gradlew integrationTest` | LLM client or agentic-loop work. Needs Ollama. | +| `./gradlew mcpIntegrationTest` | MCP client or server work. Needs `MCP_REDMINE_URL`. | +| `./gradlew pitest` | After a new behavior, to see mutants the tests leave alive. | + +Unit tests inject a `ModelClient`. Live tests stay tagged. Linux sandbox tests (`bwrap`, `firejail`) need a Linux kernel and skip on macOS. CI runs them on Ubuntu. + +A reported defect gets a regression test that fails on the current code before the fix. An existing assertion stays. When a contract change forces an edit, the test name and the contract that replaced it go in the task note. diff --git a/sdlc/agents/parts/project/project.md b/sdlc/agents/parts/project/project.md new file mode 100644 index 0000000..c3b9a81 --- /dev/null +++ b/sdlc/agents/parts/project/project.md @@ -0,0 +1,19 @@ +## Project + +Agents.KT is the JVM runtime for an AI factory. A factory is a line of `Agent` stations: one input type, one output type, one job. The same line builds a software agent or an embodied agent. Software tools are compilers, repos, HTTP, and MCP. Body tools are sensors and actuators, attached the same way. The handoff for a partner agent is [docs/ai-factories.md](docs/ai-factories.md). The product site is [agents-kt.dev](https://agents-kt.dev/). The Maven coordinate is `ai.deep-code:agents-kt`. The license is MIT, held by Deep-Code.AI. The repository is [Deep-CodeAI/Agents.KT](https://github.com/Deep-CodeAI/Agents.KT). + +The published version, the provider count, and the protocol status live in [release-metadata.yaml](release-metadata.yaml). [README.md](README.md) tracks that file. `ReleaseMetadataConsistencyTest` fails when a surface drifts. The [wiki](https://github.com/Deep-CodeAI/Agents.KT/wiki) is the learning path. When the wiki names an older published version, `release-metadata.yaml` and the README win. + +| Path | Holds | +| --- | --- | +| `AGENTS.md` | This law, assembled from `sdlc/agents/parts/project/`. Edit the part, then copy the same text into the matching import block. | +| [docs/ai-factories.md](docs/ai-factories.md) | Partner handoff: one factory, software lines and embodied lines. | +| `README.md` | Product contract: security model, shipped surface, limitations, documentation index. | +| `docs/` | In-repo guides. Start with [docs/testing.md](docs/testing.md), [docs/source-layout.md](docs/source-layout.md), [docs/composition.md](docs/composition.md), [docs/threat-model.md](docs/threat-model.md). The README Documentation list names the rest. | +| [Wiki Home](https://github.com/Deep-CodeAI/Agents.KT/wiki) | Learning path, from Installation through Best Practices. | +| `release-metadata.yaml` | `currentRelease`, `developmentVersion`, `providers`, and `protocols`. | +| `src/main/kotlin/agents_engine/` | Core runtime. | +| `agents-kt-*` | Feature modules named in `settings.gradle.kts`. | +| `sdlc/` and `tasks/` | Adopted Tatenergo.AI snapshot. Framework work stays in `src/` and the `agents-kt-*` modules. | + +JDK 21 or newer. Kotlin version and the dependency line are the ones the README Current Release section states. The Gradle wrapper is the build. `./gradlew build` is the environment check in [Building From Source](https://github.com/Deep-CodeAI/Agents.KT/wiki/Building-From-Source). diff --git a/sdlc/agents/parts/requirements.md b/sdlc/agents/parts/requirements.md new file mode 100644 index 0000000..7ea0ef2 --- /dev/null +++ b/sdlc/agents/parts/requirements.md @@ -0,0 +1,79 @@ +## Requirements + +Based on Karl E. Wiegers and Joy Beatty, Software Requirements, 3rd edition. A requirement is one testable statement of a stakeholder need. Development writes the statement. Management keeps the id, the trace, and the status true after approval. + +Specs live in `sdlc/specs/`. One file holds one requirement. + +### Levels + +Write the higher level before the lower level. A lower statement traces to one parent. + +| Prefix | Level | States | +| --- | --- | --- | +| `BR` | Business | One measured outcome: scale, meter, target, and the stakeholder who owns the number. | +| `UR` | User | One goal of one named user class. | +| `FR` | Functional | One observable behavior of the system. | +| `QA` | Quality | Scale, meter, minimum, and target for one property of a behavior. | +| `RULE` | Business rule | A policy the organization already enforces. Functional requirements reference it by id. | +| `CON` | Constraint | A mandated limit on design or operation. | +| `IF` | Interface | One external system, one data item, one direction. | +| `DATA` | Data | One entity, its fields, and the allowed values. | + +A business outcome lives on a `BR`. A user goal lives on a `UR`. An observable behavior lives on an `FR`. A mandated technology lives on a `CON`. + +### File + +`sdlc/specs/{folder}/{PREFIX}-{n}-{slug}.md` + +| Field | Holds | +| --- | --- | +| Id | The prefix and number, such as `FR-12`. | +| Priority | `H`, `M`, or `L`, from value to the parent objective, cost, and risk. `H` is required for the parent target. `M` raises that target. `L` waits. | +| Status | `draft`, `tbd`, `approved`, `implemented`, `verified`, `deferred`, or `rejected`. | +| Trace | The parent id. `FR` traces to `UR`. `UR` traces to `BR`. `QA` traces to the behavior it measures. | +| Rationale | The outcome this statement protects, in one sentence. | +| Fit | The test that fails when the statement is unmet. | + +`tbd` names the missing fact: a number, a role, or a source. An approved requirement has a fit and a parent. A rejected id stays unused. + +### User goal + +A user requirement names one user class and one goal. The body is the main success scenario as numbered steps. Each system step that stores data or returns data has its own functional requirement, traced to that user requirement. An alternate path and an exception path are their own functional requirements, traced to the same user requirement. + +Name the user classes before the first user requirement. + +### Shall + +One sentence. One behavior. + +`The shall when .` + +Two behaviors are two ids. + +| Open wording | Closed wording | +| --- | --- | +| support, handle, process | the stored result and the rejected input | +| fast, responsive, scalable | a meter, a load, and a percentile | +| user-friendly, intuitive, robust | the actor action and the visible outcome | +| several, a few, as appropriate, etc. | the count or the closed list | +| should, may | shall, or a separate id with priority `L` | + +bad: `The system shall support fast, user-friendly search of documents and export them.` + +good: `FR-12. The system shall return 20 ranked excerpts for one procurement query. Fit: on a 10 000-chunk corpus, p95 time is at most 2 seconds. Trace: UR-4.` + +### Characteristics + +Each requirement is necessary, unambiguous, feasible, prioritized, verifiable, and traced. The set for one feature covers the named user classes, stays consistent across ids, and stays true after one requirement changes. + +A fit names the actor or the corpus, the stimulus, the expected result, and the meter. + +### Scope + +Scope for a release is the list of business requirements in that release. An outcome outside the release is one line: the outcome, and the business requirement it would serve. + +### Change + +An approved requirement changes in one edit of the shall, the fit, the trace, and the test that encodes the fit. Status moves to `implemented` when that test exists, and to `verified` when that test is green. + +Code for a requirement starts after the status is `approved`. diff --git a/sdlc/agents/parts/transcripts.md b/sdlc/agents/parts/transcripts.md new file mode 100644 index 0000000..b035f21 --- /dev/null +++ b/sdlc/agents/parts/transcripts.md @@ -0,0 +1,7 @@ +## Transcripts + +Each audio recording gets a transcript in the `Транскрипты/` folder. The tree inside repeats the recording's place in the project. The file name matches the recording name. + +Transcription uses whisper.cpp, model `~/.whisper-models/ggml-large-v3-turbo.bin`, language `ru`. + +The transcript is cleaned of recognition artifacts and split into sections by topic, keeping the order of the lines. Tasks from the recording go into a separate file with statuses. From f8eb64ee125e3df7a8d28b31bb40a17e7782943e Mon Sep 17 00:00:00 2001 From: skobeltsyn Date: Thu, 12 Nov 2026 11:20:49 +0300 Subject: [PATCH 2/2] docs: drop the Tatenergo snapshot from the factory handoff Remove the adopted process parts and the Tatenergo path note. The partner brief and AGENTS.md now describe only Agents.KT. --- AGENTS.md | 1 - docs/ai-factories.md | 2 +- sdlc/agents/parts/extreme-programming.md | 35 ------- sdlc/agents/parts/language.md | 125 ----------------------- sdlc/agents/parts/project/project.md | 1 - sdlc/agents/parts/requirements.md | 79 -------------- sdlc/agents/parts/transcripts.md | 7 -- 7 files changed, 1 insertion(+), 249 deletions(-) delete mode 100644 sdlc/agents/parts/extreme-programming.md delete mode 100644 sdlc/agents/parts/language.md delete mode 100644 sdlc/agents/parts/requirements.md delete mode 100644 sdlc/agents/parts/transcripts.md diff --git a/AGENTS.md b/AGENTS.md index 28df3d7..3af7f8e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,7 +18,6 @@ The published version, the provider count, and the protocol status live in [rele | `release-metadata.yaml` | `currentRelease`, `developmentVersion`, `providers`, and `protocols`. | | `src/main/kotlin/agents_engine/` | Core runtime. | | `agents-kt-*` | Feature modules named in `settings.gradle.kts`. | -| `sdlc/` and `tasks/` | Adopted Tatenergo.AI snapshot. Framework work stays in `src/` and the `agents-kt-*` modules. | JDK 21 or newer. Kotlin version and the dependency line are the ones the README Current Release section states. The Gradle wrapper is the build. `./gradlew build` is the environment check in [Building From Source](https://github.com/Deep-CodeAI/Agents.KT/wiki/Building-From-Source). diff --git a/docs/ai-factories.md b/docs/ai-factories.md index 7094cc9..1bd0e4e 100644 --- a/docs/ai-factories.md +++ b/docs/ai-factories.md @@ -48,7 +48,7 @@ This repository is that factory's runtime. Kotlin on JDK 21+. Maven coordinate ` A software line is a library inside a JVM service, an MCP server, an A2A peer, or a same-JVM swarm. Local models start with Ollama. Cloud providers are opt-in. The provider count and the protocol status (`mcp`, `a2a`, `agui`, `nlweb`, `x402`, `agntcy`) are the fields in `release-metadata.yaml`. -Core code is `src/main/kotlin/agents_engine/`. Feature modules are the `agents-kt-*` projects in `settings.gradle.kts`. `sdlc/` and `tasks/` are an adopted Tatenergo.AI snapshot. Factory work goes in `src/` and the `agents-kt-*` modules. +Core code is `src/main/kotlin/agents_engine/`. Feature modules are the `agents-kt-*` projects in `settings.gradle.kts`. Factory work goes in `src/` and those modules. ## Embodied factory, as a target diff --git a/sdlc/agents/parts/extreme-programming.md b/sdlc/agents/parts/extreme-programming.md deleted file mode 100644 index 35af42d..0000000 --- a/sdlc/agents/parts/extreme-programming.md +++ /dev/null @@ -1,35 +0,0 @@ -## Test-first - -The minimal unit of work is one use case. The use case proceeds in baby steps. A baby step ends with a green test, each fact living once, and the architecture of the types that step touched still correct. - -### Baby step - -One baby step adds one behavior of the use case. - -1. Write one failing test for that behavior. -2. Make the test compile. -3. Make the test green with the smallest production change. -4. Remove duplication. Each fact lives once. -5. Restore the architecture. One type keeps one outcome. One file holds one entity. The layer and the package match the new-wave part. - -The next baby step starts from that tree. The use case is done when every behavior has finished a baby step. - -The run ends with every test green. - -Each test suite includes exploit tests under `tests/security`. An exploit calls the use case as another actor, with another actor's id, or with a privileged field. The test is green when the system refuses the call and the other actor's row stays unchanged. The test is red when the exploit reads or writes that row. - -An existing test stays as it is. An edit to an existing test happens when the edit is inevitable: the assertion encodes a contract that was replaced, or the test fails to compile because that contract's types changed. The task file records the test name and the reason. The old assertion is the record of application logic. Replacing it replaces that logic, and a wrong reason ships the wrong logic. - -| After the step | Holds | -| --- | --- | -| Tests | The new test is green. Every test that was green at the start of the run is green. | -| Repetition | One fact, one branch, and one query each live in one place. | -| Architecture | A controller method calls one use case. Domain stays free of HTTP framework types. | - -bad: `Add the behaviors of the use case, then clean the duplicates and the packages at the end.` - -good: `The test for one behavior is red, then green. The duplicate leaves. The type still has one outcome. The next behavior starts there.` - -bad: `Change the old assertion so the suite goes green.` - -good: `The old assertion stays. The new test is green. When the old assertion has to change, the task file names the test and the contract that replaced it.` diff --git a/sdlc/agents/parts/language.md b/sdlc/agents/parts/language.md deleted file mode 100644 index b9dc427..0000000 --- a/sdlc/agents/parts/language.md +++ /dev/null @@ -1,125 +0,0 @@ -## Language - -Use positive expressions. - -bad: `This is not X, not Y - Z` -good: `This is Z`. - -Skip bracketed asides. - -bad: `this X is so amazing innovation in Y (excitement)` -good: `Innovation X in Y makes Z significantly better` - -Use quantities. - -bad: `there are too much X for Y` -good: `For Y you need Z but given X` - -State the amounts on both sides of a limit. - -bad: `You have only 10USD left - it is impossible to do X` -good: `X costs YUSD, given 10USD` - -Keep one sentence on one mechanism. - -bad: `X, Y, Z - not by A, not by B.. - by ... F` -good: `By B using ... incorporating F we achive|get|obtain X with Y and Z.` - -Drop words that carry no fact. - -bad: `X, Y, Z, before they A.` -good: `X, Y.` - -A sentence that names an absence and stops is empty. Leave it out. - -bad: `What we are not proposing: X` - -Use the shortest wording that still carries the fact. - -bad: `One venue uplink, one org API key, 20 concurrent agent sessions` -good: `20 concurrent agent sessions using same network and API key` - -bad: `With 20 tables and 6 facilitators, a director flying blind discovers stuck tables at the debrief, which is too late.` -good: `director should be able to monitor 20 tables and 6 facilitators using ....` - -The file name already holds the title. The body holds the content. - -bad: `AI Theater — the whole program, in one table` -good: `AI Theater` - -Put totals in the lead and the breakdown under them. - -bad: `120 participants · one computer each · 240 minutes · 25 tasks · 9 gates at 80% green = 96 of 120. Computer setup runs before the event, outside the budget.` -good: `4 hours program, 120 participants, 25 tasks` - -Add a section when the text is unclear without it. - -bad: `Section Reading the X` -good: a heading appears when the paragraph under it is unclear without that heading. - -Name the objects a level is responsible for. - -bad: `Level 2 walks all 120 machines: the agent is available, the dataset is in place, the videos are on disk.` -good: `Level 2 is responsible for agent availability, datasets in place, videos on disk, and handouts at all 120 seats.` - -A schedule row states who runs the block and what the block contains. - -bad: `Who runs the day; a map of 5 blocks, 3 breaks, and 25 tasks; an 80% threshold; how to call for help; a simulated company; voice input with the Whisper model on each machine. 9 slides` -good: `Who runs the day; a description of the 5 blocks; how to call for help and what to do when the pace falls short of the 80% threshold, with a chance to catch up with support; the simulated environment (company, messenger, mail, and the rest); voice input with the Whisper model on each machine` - -A heading names the thing. - -bad: `Source material (checked, with sources)` -good: `Cases` - -State the structure in place order. - -bad: `The five-level pyramid is read from the top: purpose sets everything else` -good: `The pyramid has five levels. The domain sits above. Work with the hardware sits below.` - -Name the object of every verb. - -bad: `Reversibility: switching the harness is available for 6 of 7 tools in part 5, and editing the regulation takes a day` -good: `Reversibility: switching the harness is available for 6 of 7 tools in part 5, and editing the rules file takes a day` - -A sentence that reports a label and stops is empty. State the two items. - -bad: `Benjamin Graham described two ways to handle money and called both of them existing.` -good: `Benjamin Graham described two ways to handle money: 1) 2)` - -Put the operation and its result in one clause. - -bad: `Investing is an operation that, after analysis, promises safety of principal and an acceptable return.` -good: `Investing is an operation that secures safety of principal and an acceptable return.` - -Name the metrics and the shared cause. - -bad: `Two numbers measure different things: the first is hardware load, the second is the financial result of the pilots.` -good: `The 2 metrics shown reflect hardware load and the financial result of the pilots, with one shared factor behind the bad outcome: the decision to start was made without a measurement before the purchase.` - -Keep the term. A calque hides it. - -bad: `Frame: two ways to handle money` -good: `Two frameworks for working with funds` - -Describe the result. Address the reader in zero sentences. - -bad: `After the talk, you roll the direction you need into your company's playbook` -good: `The talk makes it possible to build a playbook for the chosen directions` - -A short sentence still names its subject and the mechanism. - -bad: `Hence the second author.` -good: `Graham's margin-of-safety calculation needs modern approaches added to it. Nassim Taleb's approach fits for black swans and antifragility: designing the system's response to a model-generation change, a vendor refusal, attacks on the perimeter, and many others.` - -One result, then the difference in method. - -bad: a paragraph that restates both definitions before the test. -good: `Investing and speculation serve one result: the return and growth of invested resources. The difference is the method. In the first case the return comes from the work of the asset. In the second it comes from revaluing the asset.` - -The title is the claim. Counts and sources sit in the body. - -bad: `Benjamin Graham's and Nassim Taleb's principles applied to investments in artificial intelligence. Six vectors, entry and exit thresholds, a source for each number.` -good: `Principles of investing in artificial intelligence.` - -Texts use verifiable facts and metrics. A diagram replaces a paragraph when the diagram carries the same facts. diff --git a/sdlc/agents/parts/project/project.md b/sdlc/agents/parts/project/project.md index c3b9a81..e180773 100644 --- a/sdlc/agents/parts/project/project.md +++ b/sdlc/agents/parts/project/project.md @@ -14,6 +14,5 @@ The published version, the provider count, and the protocol status live in [rele | `release-metadata.yaml` | `currentRelease`, `developmentVersion`, `providers`, and `protocols`. | | `src/main/kotlin/agents_engine/` | Core runtime. | | `agents-kt-*` | Feature modules named in `settings.gradle.kts`. | -| `sdlc/` and `tasks/` | Adopted Tatenergo.AI snapshot. Framework work stays in `src/` and the `agents-kt-*` modules. | JDK 21 or newer. Kotlin version and the dependency line are the ones the README Current Release section states. The Gradle wrapper is the build. `./gradlew build` is the environment check in [Building From Source](https://github.com/Deep-CodeAI/Agents.KT/wiki/Building-From-Source). diff --git a/sdlc/agents/parts/requirements.md b/sdlc/agents/parts/requirements.md deleted file mode 100644 index 7ea0ef2..0000000 --- a/sdlc/agents/parts/requirements.md +++ /dev/null @@ -1,79 +0,0 @@ -## Requirements - -Based on Karl E. Wiegers and Joy Beatty, Software Requirements, 3rd edition. A requirement is one testable statement of a stakeholder need. Development writes the statement. Management keeps the id, the trace, and the status true after approval. - -Specs live in `sdlc/specs/`. One file holds one requirement. - -### Levels - -Write the higher level before the lower level. A lower statement traces to one parent. - -| Prefix | Level | States | -| --- | --- | --- | -| `BR` | Business | One measured outcome: scale, meter, target, and the stakeholder who owns the number. | -| `UR` | User | One goal of one named user class. | -| `FR` | Functional | One observable behavior of the system. | -| `QA` | Quality | Scale, meter, minimum, and target for one property of a behavior. | -| `RULE` | Business rule | A policy the organization already enforces. Functional requirements reference it by id. | -| `CON` | Constraint | A mandated limit on design or operation. | -| `IF` | Interface | One external system, one data item, one direction. | -| `DATA` | Data | One entity, its fields, and the allowed values. | - -A business outcome lives on a `BR`. A user goal lives on a `UR`. An observable behavior lives on an `FR`. A mandated technology lives on a `CON`. - -### File - -`sdlc/specs/{folder}/{PREFIX}-{n}-{slug}.md` - -| Field | Holds | -| --- | --- | -| Id | The prefix and number, such as `FR-12`. | -| Priority | `H`, `M`, or `L`, from value to the parent objective, cost, and risk. `H` is required for the parent target. `M` raises that target. `L` waits. | -| Status | `draft`, `tbd`, `approved`, `implemented`, `verified`, `deferred`, or `rejected`. | -| Trace | The parent id. `FR` traces to `UR`. `UR` traces to `BR`. `QA` traces to the behavior it measures. | -| Rationale | The outcome this statement protects, in one sentence. | -| Fit | The test that fails when the statement is unmet. | - -`tbd` names the missing fact: a number, a role, or a source. An approved requirement has a fit and a parent. A rejected id stays unused. - -### User goal - -A user requirement names one user class and one goal. The body is the main success scenario as numbered steps. Each system step that stores data or returns data has its own functional requirement, traced to that user requirement. An alternate path and an exception path are their own functional requirements, traced to the same user requirement. - -Name the user classes before the first user requirement. - -### Shall - -One sentence. One behavior. - -`The shall when .` - -Two behaviors are two ids. - -| Open wording | Closed wording | -| --- | --- | -| support, handle, process | the stored result and the rejected input | -| fast, responsive, scalable | a meter, a load, and a percentile | -| user-friendly, intuitive, robust | the actor action and the visible outcome | -| several, a few, as appropriate, etc. | the count or the closed list | -| should, may | shall, or a separate id with priority `L` | - -bad: `The system shall support fast, user-friendly search of documents and export them.` - -good: `FR-12. The system shall return 20 ranked excerpts for one procurement query. Fit: on a 10 000-chunk corpus, p95 time is at most 2 seconds. Trace: UR-4.` - -### Characteristics - -Each requirement is necessary, unambiguous, feasible, prioritized, verifiable, and traced. The set for one feature covers the named user classes, stays consistent across ids, and stays true after one requirement changes. - -A fit names the actor or the corpus, the stimulus, the expected result, and the meter. - -### Scope - -Scope for a release is the list of business requirements in that release. An outcome outside the release is one line: the outcome, and the business requirement it would serve. - -### Change - -An approved requirement changes in one edit of the shall, the fit, the trace, and the test that encodes the fit. Status moves to `implemented` when that test exists, and to `verified` when that test is green. - -Code for a requirement starts after the status is `approved`. diff --git a/sdlc/agents/parts/transcripts.md b/sdlc/agents/parts/transcripts.md deleted file mode 100644 index b035f21..0000000 --- a/sdlc/agents/parts/transcripts.md +++ /dev/null @@ -1,7 +0,0 @@ -## Transcripts - -Each audio recording gets a transcript in the `Транскрипты/` folder. The tree inside repeats the recording's place in the project. The file name matches the recording name. - -Transcription uses whisper.cpp, model `~/.whisper-models/ggml-large-v3-turbo.bin`, language `ru`. - -The transcript is cleaned of recognition artifacts and split into sections by topic, keeping the order of the lines. Tasks from the recording go into a separate file with statuses.