housekeeping: sync docs and tests

exercises/practice/anagram/.docs/instructions.md

@@ -1,9 +1,9 @@
 # Instructions
 
-An anagram is a rearrangement of letters to form a new word: for example `"owns"` is an anagram of `"snow"`.
-A word is not its own anagram: for example, `"stop"` is not an anagram of `"stop"`.
+Your task is to, given a target word and a set of candidate words, to find the subset of the candidates that are anagrams of the target.
 
-Given a target word and a set of candidate words, this exercise requests the anagram set: the subset of the candidates that are anagrams of the target.
+An anagram is a rearrangement of letters to form a new word: for example `"owns"` is an anagram of `"snow"`.
+A word is _not_ its own anagram: for example, `"stop"` is not an anagram of `"stop"`.
 
 The target and candidates are words of one or more ASCII alphabetic characters (`A`-`Z` and `a`-`z`).
 Lowercase and uppercase characters are equivalent: for example, `"PoTS"` is an anagram of `"sTOp"`, but `StoP` is not an anagram of `sTOp`.

exercises/practice/anagram/.docs/introduction.md

@@ -0,0 +1,12 @@
+# Introduction
+
+At a garage sale, you find a lovely vintage typewriter at a bargain price!
+Excitedly, you rush home, insert a sheet of paper, and start typing away.
+However, your excitement wanes when you examine the output: all words are garbled!
+For example, it prints "stop" instead of "post" and "least" instead of "stale."
+Carefully, you try again, but now it prints "spot" and "slate."
+After some experimentation, you find there is a random delay before each letter is printed, which messes up the order.
+You now understand why they sold it for so little money!
+
+You realize this quirk allows you to generate anagrams, which are words formed by rearranging the letters of another word.
+Pleased with your finding, you spend the rest of the day generating hundreds of anagrams.

exercises/practice/anagram/.meta/tests.toml

@@ -77,3 +77,11 @@ include = false
 [33d3f67e-fbb9-49d3-a90e-0beb00861da7]
 description = "words other than themselves can be anagrams"
 reimplements = "a0705568-628c-4b55-9798-82e4acde51ca"
+
+[a6854f66-eec1-4afd-a137-62ef2870c051]
+description = "handles case of greek letters"
+include = false
+
+[fd3509e5-e3ba-409d-ac3d-a9ac84d13296]
+description = "different characters may have the same bytes"
+include = false

exercises/practice/change/.meta/tests.toml

@@ -33,6 +33,9 @@ description = "possible change without unit coins available"
 [9a166411-d35d-4f7f-a007-6724ac266178]
 description = "another possible change without unit coins available"
 
+[ce0f80d5-51c3-469d-818c-3e69dbd25f75]
+description = "a greedy approach is not optimal"
+
 [bbbcc154-e9e9-4209-a4db-dd6d81ec26bb]
 description = "no coins make 0 change"
 

exercises/practice/change/change.spec.wren

@@ -47,6 +47,11 @@ Testie.test("Change") { |do, skip|
     Expect.value(result).toEqual([])
   }
 
+  skip.test("a greedy approach is not optimal") {
+    var result = Change.findMinimumCoins(20, [1, 10, 11])
+    Expect.value(result).toEqual([10, 10])
+  }
+
   skip.test("error testing for change smaller than the smallest of coins") {
     Expect.that {
       Change.findMinimumCoins(3, [5, 10])

exercises/practice/custom-set/.meta/tests.toml

@@ -114,6 +114,9 @@ description = "Difference (or Complement) of a set is a set of all elements that
 [c5ac673e-d707-4db5-8d69-7082c3a5437e]
 description = "Difference (or Complement) of a set is a set of all elements that are only in the first set -> difference of two non-empty sets is a set of elements that are only in the first set"
 
+[20d0a38f-7bb7-4c4a-ac15-90c7392ecf2b]
+description = "Difference (or Complement) of a set is a set of all elements that are only in the first set -> difference removes all duplicates in the first set"
+
 [c45aed16-5494-455a-9033-5d4c93589dc6]
 description = "Union returns a set of all elements in either set -> union of empty sets is an empty set"
 

exercises/practice/custom-set/custom-set.spec.wren

@@ -211,6 +211,12 @@ Testie.test("CustomSet") { |do, skip|
       var expected = CustomSet.new([1, 3])
       Expect.value(actual.eql(expected)).toBe(true)
     }
+
+    skip.test("difference removes all duplicates in the first set") {
+      var actual = CustomSet.new([1, 1]).difference(CustomSet.new([1]))
+      var expected = CustomSet.new([])
+      Expect.value(actual.eql(expected)).toBe(true)
+    }
   }
 
   do.describe("union: returns a set of all elements in either set") {

exercises/practice/darts/.docs/instructions.md

@@ -1,6 +1,6 @@
 # Instructions
 
-Write a function that returns the earned points in a single toss of a Darts game.
+Calculate the points scored in a single toss of a Darts game.
 
 [Darts][darts] is a game where players throw darts at a [target][darts-target].
 
@@ -16,7 +16,7 @@ In our particular instance of the game, the target rewards 4 different amounts o
 The outer circle has a radius of 10 units (this is equivalent to the total radius for the entire target), the middle circle a radius of 5 units, and the inner circle a radius of 1.
 Of course, they are all centered at the same point — that is, the circles are [concentric][] defined by the coordinates (0, 0).
 
-Write a function that given a point in the target (defined by its [Cartesian coordinates][cartesian-coordinates] `x` and `y`, where `x` and `y` are [real][real-numbers]), returns the correct amount earned by a dart landing at that point.
+Given a point in the target (defined by its [Cartesian coordinates][cartesian-coordinates] `x` and `y`, where `x` and `y` are [real][real-numbers]), calculate the correct score earned by a dart landing at that point.
 
 ## Credit
 

exercises/practice/darts/.meta/config.json

@@ -13,6 +13,6 @@
       ".meta/proof.ci.wren"
     ]
   },
-  "blurb": "Write a function that returns the earned points in a single toss of a Darts game.",
+  "blurb": "Calculate the points scored in a single toss of a Darts game.",
   "source": "Inspired by an exercise created by a professor Della Paolera in Argentina"
 }

exercises/practice/flatten-array/.docs/instructions.md

@@ -2,7 +2,7 @@
 
 Take a nested list and return a single flattened list with all values except nil/null.
 
-The challenge is to write a function that accepts an arbitrarily-deep nested list-like structure and returns a flattened structure without any nil/null values.
+The challenge is to take an arbitrarily-deep nested list-like structure and produce a flattened structure without any nil/null values.
 
 For example:
 

exercises/practice/knapsack/.meta/tests.toml

@@ -11,6 +11,11 @@
 
 [a4d7d2f0-ad8a-460c-86f3-88ba709d41a7]
 description = "no items"
+include = false
+
+[3993a824-c20e-493d-b3c9-ee8a7753ee59]
+description = "no items"
+reimplements = "a4d7d2f0-ad8a-460c-86f3-88ba709d41a7"
 
 [1d39e98c-6249-4a8b-912f-87cb12e506b0]
 description = "one item, too heavy"

exercises/practice/matching-brackets/.docs/instructions.md

@@ -1,4 +1,5 @@
 # Instructions
 
 Given a string containing brackets `[]`, braces `{}`, parentheses `()`, or any combination thereof, verify that any and all pairs are matched and nested correctly.
-The string may also contain other characters, which for the purposes of this exercise should be ignored.
+Any other characters should be ignored.
+For example, `"{what is (42)}?"` is balanced and `"[text}"` is not.

exercises/practice/matching-brackets/.docs/introduction.md

@@ -0,0 +1,8 @@
+# Introduction
+
+You're given the opportunity to write software for the Bracketeer™, an ancient but powerful mainframe.
+The software that runs on it is written in a proprietary language.
+Much of its syntax is familiar, but you notice _lots_ of brackets, braces and parentheses.
+Despite the Bracketeer™ being powerful, it lacks flexibility.
+If the source code has any unbalanced brackets, braces or parentheses, the Bracketeer™ crashes and must be rebooted.
+To avoid such a scenario, you start writing code that can verify that brackets, braces, and parentheses are balanced before attempting to run it on the Bracketeer™.

exercises/practice/parallel-letter-frequency/.docs/instructions.md

@@ -4,4 +4,4 @@ Count the frequency of letters in texts using parallel computation.
 
 Parallelism is about doing things in parallel that can also be done sequentially.
 A common example is counting the frequency of letters.
-Create a function that returns the total frequency of each letter in a list of texts and that employs parallelism.
+Employ parallelism to calculate the total frequency of each letter in a list of texts.

exercises/practice/parallel-letter-frequency/.meta/tests.toml

@@ -39,8 +39,7 @@ description = "ignore numbers"
 [aa9f97ac-3961-4af1-88e7-6efed1bfddfd]
 description = "Unicode letters"
 include = false
-comment = "wren doesn't have a lot of string manipulation functionality"
-comment = "it can't lowercase an arbitrary unicode letter"
+comment = "wren doesn't have a lot of string manipulation functionality; it can't lowercase an arbitrary unicode letter"
 
 [7b1da046-701b-41fc-813e-dcfb5ee51813]
 description = "combination of lower- and uppercase letters, punctuation and white space"

exercises/practice/perfect-numbers/.docs/instructions.md

@@ -2,22 +2,38 @@
 
 Determine if a number is perfect, abundant, or deficient based on Nicomachus' (60 - 120 CE) classification scheme for positive integers.
 
-The Greek mathematician [Nicomachus][nicomachus] devised a classification scheme for positive integers, identifying each as belonging uniquely to the categories of **perfect**, **abundant**, or **deficient** based on their [aliquot sum][aliquot-sum].
-The aliquot sum is defined as the sum of the factors of a number not including the number itself.
+The Greek mathematician [Nicomachus][nicomachus] devised a classification scheme for positive integers, identifying each as belonging uniquely to the categories of [perfect](#perfect), [abundant](#abundant), or [deficient](#deficient) based on their [aliquot sum][aliquot-sum].
+The _aliquot sum_ is defined as the sum of the factors of a number not including the number itself.
 For example, the aliquot sum of `15` is `1 + 3 + 5 = 9`.
 
-- **Perfect**: aliquot sum = number
-  - 6 is a perfect number because (1 + 2 + 3) = 6
-  - 28 is a perfect number because (1 + 2 + 4 + 7 + 14) = 28
-- **Abundant**: aliquot sum > number
-  - 12 is an abundant number because (1 + 2 + 3 + 4 + 6) = 16
-  - 24 is an abundant number because (1 + 2 + 3 + 4 + 6 + 8 + 12) = 36
-- **Deficient**: aliquot sum < number
-  - 8 is a deficient number because (1 + 2 + 4) = 7
-  - Prime numbers are deficient
-
-Implement a way to determine whether a given number is **perfect**.
-Depending on your language track, you may also need to implement a way to determine whether a given number is **abundant** or **deficient**.
+## Perfect
+
+A number is perfect when it equals its aliquot sum.
+For example:
+
+- `6` is a perfect number because `1 + 2 + 3 = 6`
+- `28` is a perfect number because `1 + 2 + 4 + 7 + 14 = 28`
+
+## Abundant
+
+A number is abundant when it is less than its aliquot sum.
+For example:
+
+- `12` is an abundant number because `1 + 2 + 3 + 4 + 6 = 16`
+- `24` is an abundant number because `1 + 2 + 3 + 4 + 6 + 8 + 12 = 36`
+
+## Deficient
+
+A number is deficient when it is greater than its aliquot sum.
+For example:
+
+- `8` is a deficient number because `1 + 2 + 4 = 7`
+- Prime numbers are deficient
+
+## Task
+
+Implement a way to determine whether a given number is [perfect](#perfect).
+Depending on your language track, you may also need to implement a way to determine whether a given number is [abundant](#abundant) or [deficient](#deficient).
 
 [nicomachus]: https://en.wikipedia.org/wiki/Nicomachus
 [aliquot-sum]: https://en.wikipedia.org/wiki/Aliquot_sum

exercises/practice/queen-attack/.docs/instructions.md

@@ -8,18 +8,14 @@ A chessboard can be represented by an 8 by 8 array.
 
 So if you are told the white queen is at `c5` (zero-indexed at column 2, row 3) and the black queen at `f2` (zero-indexed at column 5, row 6), then you know that the set-up is like so:
 
-```text
-  a b c d e f g h
-8 _ _ _ _ _ _ _ _ 8
-7 _ _ _ _ _ _ _ _ 7
-6 _ _ _ _ _ _ _ _ 6
-5 _ _ W _ _ _ _ _ 5
-4 _ _ _ _ _ _ _ _ 4
-3 _ _ _ _ _ _ _ _ 3
-2 _ _ _ _ _ B _ _ 2
-1 _ _ _ _ _ _ _ _ 1
-  a b c d e f g h
-```
+![A chess board with two queens. Arrows emanating from the queen at c5 indicate possible directions of capture along file, rank and diagonal.](https://assets.exercism.org/images/exercises/queen-attack/queen-capture.svg)
 
 You are also able to answer whether the queens can attack each other.
 In this case, that answer would be yes, they can, because both pieces share a diagonal.
+
+## Credit
+
+The chessboard image was made by [habere-et-dispertire][habere-et-dispertire] using LaTeX and the [chessboard package][chessboard-package] by Ulrike Fischer.
+
+[habere-et-dispertire]: https://exercism.org/profiles/habere-et-dispertire
+[chessboard-package]: https://github.com/u-fischer/chessboard

exercises/practice/raindrops/.meta/config.json

@@ -13,7 +13,7 @@
       ".meta/proof.ci.wren"
     ]
   },
-  "blurb": "Convert a number to a string, the content of which depends on the number's factors.",
+  "blurb": "Convert a number into its corresponding raindrop sounds - Pling, Plang and Plong.",
   "source": "A variation on FizzBuzz, a famous technical interview question that is intended to weed out potential candidates. That question is itself derived from Fizz Buzz, a popular children's game for teaching division.",
   "source_url": "https://en.wikipedia.org/wiki/Fizz_buzz"
 }

exercises/practice/reverse-string/.meta/tests.toml

@@ -1,6 +1,13 @@
-# This is an auto-generated file. Regular comments will be removed when this
-# file is regenerated. Regenerating will not touch any manually added keys,
-# so comments can be added in a "comment" key.
+# This is an auto-generated file.
+#
+# Regenerating this file via `configlet sync` will:
+# - Recreate every `description` key/value pair
+# - Recreate every `reimplements` key/value pair, where they exist in problem-specifications
+# - Remove any `include = true` key/value pair (an omitted `include` key implies inclusion)
+# - Preserve any other key/value pair
+#
+# As user-added comments (using the # character) will be removed when this file
+# is regenerated, comments can be added via a `comment` key.
 
 [c3b7d806-dced-49ee-8543-933fd1719b1c]
 description = "an empty string"
@@ -19,3 +26,15 @@ description = "a palindrome"
 
 [b9e7dec1-c6df-40bd-9fa3-cd7ded010c4c]
 description = "an even-sized word"
+
+[1bed0f8a-13b0-4bd3-9d59-3d0593326fa2]
+description = "wide characters"
+include = false
+
+[93d7e1b8-f60f-4f3c-9559-4056e10d2ead]
+description = "grapheme cluster with pre-combined form"
+include = false
+
+[1028b2c1-6763-4459-8540-2da47ca512d9]
+description = "grapheme clusters"
+include = false

exercises/practice/roman-numerals/.meta/tests.toml

@@ -84,5 +84,8 @@ description = "3000 is MMM"
 [3bc4b41c-c2e6-49d9-9142-420691504336]
 description = "3001 is MMMI"
 
+[2f89cad7-73f6-4d1b-857b-0ef531f68b7e]
+description = "3888 is MMMDCCCLXXXVIII"
+
 [4e18e96b-5fbb-43df-a91b-9cb511fe0856]
 description = "3999 is MMMCMXCIX"

exercises/practice/roman-numerals/roman-numerals.spec.wren

@@ -27,5 +27,6 @@ Testie.test("Roman Numerals") { |do, skip|
   skip.test("converts 1024") { Expect.value(Number.toRoman(1024)).toEqual("MXXIV") }
   skip.test("converts 3000") { Expect.value(Number.toRoman(3000)).toEqual("MMM") }
   skip.test("converts 3001") { Expect.value(Number.toRoman(3001)).toEqual("MMMI") }
+  skip.test("converts 3888") { Expect.value(Number.toRoman(3888)).toEqual("MMMDCCCLXXXVIII") }
   skip.test("converts 3999") { Expect.value(Number.toRoman(3999)).toEqual("MMMCMXCIX") }
 }

exercises/practice/space-age/.docs/instructions.md

@@ -1,25 +1,28 @@
 # Instructions
 
-Given an age in seconds, calculate how old someone would be on:
+Given an age in seconds, calculate how old someone would be on a planet in our Solar System.
 
-- Mercury: orbital period 0.2408467 Earth years
-- Venus: orbital period 0.61519726 Earth years
-- Earth: orbital period 1.0 Earth years, 365.25 Earth days, or 31557600 seconds
-- Mars: orbital period 1.8808158 Earth years
-- Jupiter: orbital period 11.862615 Earth years
-- Saturn: orbital period 29.447498 Earth years
-- Uranus: orbital period 84.016846 Earth years
-- Neptune: orbital period 164.79132 Earth years
+One Earth year equals 365.25 Earth days, or 31,557,600 seconds.
+If you were told someone was 1,000,000,000 seconds old, their age would be 31.69 Earth-years.
 
-So if you were told someone were 1,000,000,000 seconds old, you should
-be able to say that they're 31.69 Earth-years old.
+For the other planets, you have to account for their orbital period in Earth Years:
 
-If you're wondering why Pluto didn't make the cut, go watch [this YouTube video][pluto-video].
+| Planet  | Orbital period in Earth Years |
+| ------- | ----------------------------- |
+| Mercury | 0.2408467                     |
+| Venus   | 0.61519726                    |
+| Earth   | 1.0                           |
+| Mars    | 1.8808158                     |
+| Jupiter | 11.862615                     |
+| Saturn  | 29.447498                     |
+| Uranus  | 84.016846                     |
+| Neptune | 164.79132                     |
 
-Note: The actual length of one complete orbit of the Earth around the sun is closer to 365.256 days (1 sidereal year).
+~~~~exercism/note
+The actual length of one complete orbit of the Earth around the sun is closer to 365.256 days (1 sidereal year).
 The Gregorian calendar has, on average, 365.2425 days.
 While not entirely accurate, 365.25 is the value used in this exercise.
 See [Year on Wikipedia][year] for more ways to measure a year.
 
-[pluto-video]: https://www.youtube.com/watch?v=Z_2gbGXzFbs
 [year]: https://en.wikipedia.org/wiki/Year#Summary
+~~~~

exercises/practice/space-age/.docs/introduction.md

@@ -0,0 +1,20 @@
+# Introduction
+
+The year is 2525 and you've just embarked on a journey to visit all planets in the Solar System (Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus and Neptune).
+The first stop is Mercury, where customs require you to fill out a form (bureaucracy is apparently _not_ Earth-specific).
+As you hand over the form to the customs officer, they scrutinize it and frown.
+"Do you _really_ expect me to believe you're just 50 years old?
+You must be closer to 200 years old!"
+
+Amused, you wait for the customs officer to start laughing, but they appear to be dead serious.
+You realize that you've entered your age in _Earth years_, but the officer expected it in _Mercury years_!
+As Mercury's orbital period around the sun is significantly shorter than Earth, you're actually a lot older in Mercury years.
+After some quick calculations, you're able to provide your age in Mercury Years.
+The customs officer smiles, satisfied, and waves you through.
+You make a mental note to pre-calculate your planet-specific age _before_ future customs checks, to avoid such mix-ups.
+
+~~~~exercism/note
+If you're wondering why Pluto didn't make the cut, go watch [this YouTube video][pluto-video].
+
+[pluto-video]: https://www.youtube.com/watch?v=Z_2gbGXzFbs
+~~~~

exercises/practice/two-bucket/.docs/instructions.md

@@ -11,7 +11,7 @@ There are some rules that your solution must follow:
      b) the second bucket is full
   2. Emptying a bucket and doing nothing to the other.
   3. Filling a bucket and doing nothing to the other.
-- After an action, you may not arrive at a state where the starting bucket is empty and the other bucket is full.
+- After an action, you may not arrive at a state where the initial starting bucket is empty and the other bucket is full.
 
 Your program will take as input: